1. Docs
2. API
3. Markers API

Markers API

Markers indicate 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.

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, this field 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.

Authorization and Headers 

The only expected header is X-Honeycomb-Team, which is your API key, and it is required. The API key must have the Manage Markers permission. Learn more about API keys.

Create a Dataset Marker 

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

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

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

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

Create Example Request 

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

Create 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 Dataset Marker 

Any of the modifiable fields in a Dataset 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 Dataset Marker, including any updated values. If you do not include an existing field in the payload, it will be erased.

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

Update Example Request 

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

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

Update 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 Dataset Marker 

Dataset 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 Dataset Marker has been successfully deleted, the API will respond with 200 and the deleted Marker in the body of the response.

Delete Example Request 

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

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

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

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.

List All Example Request 

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

Environment Markers 

Environment markers can be managed with the same APIs as above, using the special __all__ token in the URL instead of a dataset name.

Environment markers not associated with a dataset. Instead, they are visible by default on all datasets within an environment and can be toggled within the Filter Markers UI:

All API actions above are available to environment markers as well (create, list, update, delete).

Environment Marker Example Request 

curl https://api.honeycomb.io/1/markers/__all__ -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"message":"Postgres upgrade", "type":"infra", "start_time":1471040808}'

Did you find what you were looking for?

Yes No

Additional Feedback (Optional)

---

If you have questions, join our Pollinators Community Slack, or for Pro/Enterprise users, contact Support at support@honeycomb.io.

Submit