Markers API

Markers are for indicating points in time on your graphs where interesting things happen, such as deploys or outages. You can list, create, update, and delete Markers. The Marker UI is illustrated in the section on manually creating markers.

All Marker endpoints operate on a dataset and use the Team API key to authenticate. All requests should be made via HTTPS to api.honeycomb.io.

Fields on a Marker

Marker objects have the following assignable fields. All fields are optional, and may be modified at any time.

start_time: Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives at the API. Expressed in Unix Time, aka seconds since the epoch
end_time: Optional. Specifying end time will allow you to record a Marker representing a time range (such as a 5 minute deploy). This range will be highlighted when rendering a graph. Expressed in Unix Time, aka seconds since the epoch
message: a string describing this specific Marker. This string will appear above the Marker line on a graph
type: a string grouping similar Markers, eg ‘deploys’. All Markers of the same type will appear in the same color on the graph
url: a target for the Marker. If you click on the Marker text, it will take you to this URL. For a deploy, it might be a link to the build system showing the build log for the version that was deployed

When a Marker is created or updated, the following fields are assigned. They may not be modified.

id: The Marker ID is a 6 character hexadecimal string and is assigned on Marker creation
created_at: The time the Marker was created
updated_at: The time of the most recent modification to the Marker. It is updated every time the Marker is changed.
color: You can assign a color to a Marker type in the Dataset Advanced settings page in the UI. The color field will be populated when you list events.

Headers

The only expected header is X-Honeycomb-Team, which is your Team API key. It is required.

Create a Marker

Markers are created by sending a POST request to /1/markers/<DATASET_NAME>

The Marker body should be a JSON encoded object including as many of the Marker fields as desired. ID may not be set during creation.

When a Marker is successfully created, the API will respond with HTTP status 201 and will return a JSON object representing that Marker.

An example, creating a deploy Marker on the TestViaCurl dataset:

Example Request

$ curl https://api.honeycomb.io/1/markers/TestViaCurl -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471040808}'

Example Response

{
  "created_at":"2016-08-13T05:39:42Z",
  "updated_at":"2016-08-13T05:39:42Z",
  "start_time":1471040808,
  "message":"backend deploy #123",
  "type":"deploy",
  "id":"d1c84ec0"
}

Update a Marker

Any of the modifiable fields in a Marker can be updated by sending a PUT request to /1/markers/<dataset>/<marker_id>.

The PUT request should have as its body a JSON object containing all the user-settable fields for this Marker, including any updated values. If you do not include an existing field in the payload, it will be erased.

When a Marker has been successfully updated, the API returns code 200 and the updated Marker as the body of the response.

As an example, this curl request will change the start time of the Marker created above:

Example Request

$ curl https://api.honeycomb.io/1/markers/TestViaCurl/d1c84ec0 -X PUT  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471067108}'

Example Response

{
  "created_at":"2016-08-13T05:39:42Z",
  "updated_at":"2016-08-13T05:39:42Z",
  "start_time":1471067108,
  "message":"backend deploy #123",
  "type":"deploy",
  "id":"d1c84ec0"
}

Delete a Marker

Markers may be deleted by sending a DELETE request to /1/markers/<dataset>/<marker_id>.

The body of the DELETE request should be empty.

When the Marker has been successfully deleted, the API will respond with 200 and the deleted Marker in the body of the response.

As an example, this curl request will delete the Marker we created and modified above:

Example Request

$ curl https://api.honeycomb.io/1/markers/TestViaCurl/d1c84ec0 -X DELETE  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Example Response

{
  "created_at":"2016-08-13T05:39:42Z",
  "updated_at":"2016-08-13T05:39:42Z",
  "start_time":1471067108,
  "message":"backend deploy #123",
  "type":"deploy",
  "id":"d1c84ec0"
}

List all Markers

All the Markers in a dataset may be retrieved by sending a GET request to /1/markers/<DATASET_NAME>

Example Request

$ curl https://api.honeycomb.io/1/markers/DATASET_NAME \
    -X GET -H "X-Honeycomb-Team: YOUR_API_KEY"

A successful response will return HTTP 200 and a JSON list of all Marker objects for the dataset.

Invalid input will result in a HTTP 422 being returned.