We use cookies or similar technologies to personalize your online experience and tailor marketing to you. Many of our product features require cookies to function properly. Your use of this site and online product constitutes your consent to these personalization technologies. Read our Privacy Policy to find out more.

X

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.

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.

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

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 200 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.