Marker Settings API | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

Marker Settings API

Marker Settings are for grouping similar Markers. For example, “deploys”, under the same color that shows on a graph. You can list, create, update, and delete Marker Settings.

Fields on Marker Settings 

Marker Settings objects have the following assignable fields:

  • type: (required) a string grouping similar Markers. For example, “deploys.” All Markers of the same type will appear in the same color on the graph.
  • 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.

When a Marker Setting is created or updated, the following fields are assigned and may not be manually modified:

  • id: The Marker Settings ID is a 6 character hexadecimal string and is assigned on Marker Settings creation
  • created_at: The time the Marker Setting was created
  • updated_at: The time of the most recent modification to the Marker Setting. It is updated every time the Marker Type Settings is changed.

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 Setting 

Marker Settings are created by sending a POST request to /1/marker_settings/<DATASET_NAME>

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

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

Create Example Request 

Create a “deploy” Marker Setting on the TestViaCurl dataset:

curl https://api.honeycomb.io/1/marker_settings/test-via-curl -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"type":"deploy", "color":"#7b1fa2"}'

Create Example Response 

{
  "id": "gwAHiE5TS4j",
  "type": "deploy",
  "color": "#7b1fa2",
  "created_at": "2022-09-15T05:39:42Z",
  "updated_at": "2022-09-15T05:39:42Z"
}

Update a Dataset Marker Setting 

Any of the modifiable fields in a Marker can be updated by sending a PUT request to /1/marker_settings/<dataset>/<marker_setting_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 Setting has been successfully updated, the API returns code 200 and the updated Marker Settings as the body of the response.

Update Example Request 

This curl request changes the color of an existing “deploy” Marker:

curl https://api.honeycomb.io/1/marker_settings/test-via-curl/gwAHiE5TS4j -X PUT  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"type":"deploy", "color":"#b71c1c"}'

Update Example Response 

{
  "id": "gwAHiE5TS4j",
  "type": "deploy",
  "color": "#b71c1c",
  "created_at": "2022-09-15T05:39:42Z",
  "updated_at": "2022-09-15T05:39:42Z"
}

Delete a Dataset Marker Setting 

Delete Marker Settings by sending a DELETE request to /1/marker_settings/<dataset>/<marker_setting_id>.

The body of the DELETE request should be empty.

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

Delete Example Request 

This curl request deletes the Marker Settings associated with its Marker Setting ID:

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

Delete Example Response 

{
  "id": "gwAHiE5TS4j",
  "type": "deploy",
  "color": "#b71c1c",
  "created_at": "2022-09-15T05:39:42Z",
  "updated_at": "2022-09-15T05:39:42Z"
}

List All Marker Settings 

All the Marker Settings in a dataset may be retrieved by sending a GET request to /1/marker_settings/<DATASET_NAME>.

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

Invalid input will result in a HTTP 422 being returned.

List All Example Request 

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

Environment Marker Settings 

Honeycomb Classic users do not have environments and therefore cannot use environment marker settings.

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

Environment marker settings are not associated with a dataset. Instead, they are visible by default on all datasets within an environment.

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

Environment Marker Settings Example Request 

curl https://api.honeycomb.io/1/marker_settings/__all__ -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"type":"infra", "color":"#b71c1c"}'

Did you find what you were looking for?