The API allows programmatic management of many resources within Honeycomb.
Please report any discrepancies with actual API behavior in Pollinators Slack or to Honeycomb Support.
E-mail support@honeycomb.io
License Apache 2.0
The API allows programmatic management of many resources within Honeycomb.
Please report any discrepancies with actual API behavior in Pollinators Slack or to Honeycomb Support.
API Keys have various scopes permissions and belong to a specific Team or Environment.
Any valid Honeycomb ingest or configuration API Key will work with this endpoint. Learn more about API keys.
These endpoints can be used to validate authentication for a key, to determine what authorizations have been granted to a key, and to determine the Team and Environment that a key belongs to.
A description of the Board.
The number of columns to layout on the board.
A list of SLO IDs to add to the board
curl -i -X POST \
https://api.honeycomb.io/1/boards \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "My Board",
"description": "A board created via the API",
"style": "visual",
"column_layout": "multi",
"queries": [
{
"caption": "context for this query",
"graph_settings": {
"hide_markers": false,
"log_scale": false,
"omit_missing_values": false,
"stacked_graphs": false,
"utc_xaxis": false,
"overlaid_charts": false
},
"query_style": "graph",
"dataset": "My Dataset",
"query_id": "abc1234e",
"query": null,
"query_annotation_id": "e4c24a35"
}
],
"slos": [
"BGfyxhFto",
"dF1URaPGL",
"oSxbG7eiA"
]
}'{ "name": "My Board", "description": "A board created via the API", "style": "visual", "column_layout": "multi", "queries": [ { … } ], "slos": [ "BGfyxhFto", "dF1URaPGL", "oSxbG7eiA" ], "links": { "board_url": "https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd" }, "id": "2NeeaE9bBLd" }
curl -i -X GET \
https://api.honeycomb.io/1/boards \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description of the Board.
The number of columns to layout on the board.
A list of SLO IDs to add to the board
All boards are displayed visually in the UI. The field can still be sent, but it will have no functional effect in the UI.
[ { "name": "My Board", "description": "A board created via the API", "style": "visual", "column_layout": "multi", "queries": [ … ], "slos": [ … ], "links": { … }, "id": "2NeeaE9bBLd" } ]
curl -i -X GET \
'https://api.honeycomb.io/1/boards/{boardId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'{ "name": "My Board", "description": "A board created via the API", "style": "visual", "column_layout": "multi", "queries": [ { … } ], "slos": [ "BGfyxhFto", "dF1URaPGL", "oSxbG7eiA" ], "links": { "board_url": "https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd" }, "id": "2NeeaE9bBLd" }
A description of the Board.
The number of columns to layout on the board.
A list of SLO IDs to add to the board
curl -i -X PUT \
'https://api.honeycomb.io/1/boards/{boardId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "My Board",
"description": "A board created via the API",
"style": "visual",
"column_layout": "multi",
"queries": [
{
"caption": "context for this query",
"graph_settings": {
"hide_markers": false,
"log_scale": false,
"omit_missing_values": false,
"stacked_graphs": false,
"utc_xaxis": false,
"overlaid_charts": false
},
"query_style": "graph",
"dataset": "My Dataset",
"query_id": "abc1234e",
"query": null,
"query_annotation_id": "e4c24a35"
}
],
"slos": [
"BGfyxhFto",
"dF1URaPGL",
"oSxbG7eiA"
]
}'{ "name": "My Board", "description": "A board created via the API", "style": "visual", "column_layout": "multi", "queries": [ { … } ], "slos": [ "BGfyxhFto", "dF1URaPGL", "oSxbG7eiA" ], "links": { "board_url": "https://ui.honeycomb.io/myteam/environments/myenvironment/board/2NeeaE9bBLd" }, "id": "2NeeaE9bBLd" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/boards/{boardId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'This feature is available as part of the Honeycomb Pro and Enterprise plans.
Burn Alerts notify you when issues impact your SLO budget. Learn more about Burn Alerts here.
This API allows you to list, create, update, and delete burn alerts.
A description of the Burn Alert.
One of the supported alert types:
exhaustion_time: Notifies when you are about to run out of SLO budget within a specified number of hours.budget_rate: Notifies when budget drops by at least a specified percentage within a defined time window.Required when alert_type is exhaustion_time.
Must not be specified when alert_type is budget_rate.
Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached.
Details about the SLO associated with the burn alert.
A list of Recipients to notify when an alert fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
One of the supported Recipient Types
The target of the notification. For example, the specific Slack channel or email address. For Recipients of type = "webhook" or type = "msteams_workflow", this will be the Name in the UI and webhook_name in the Recipients API. Deprecated: Use the Recipients API first, then pass the Recipient ID.
curl -i -X POST \
'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"description": "Use this runbook if this alert fires.",
"alert_type": "exhaustion_time",
"exhaustion_minutes": 120,
"slo": {
"id": "2LBq9LckbcA"
},
"recipients": [
{
"id": "abcd123",
"type": "email",
"target": "alerts@example.com"
}
]
}'Created
A description of the Burn Alert.
Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.
The ISO8601-formatted time when the Burn Alert was created.
The ISO8601-formatted time when the Burn Alert was updated.
One of the supported alert types:
exhaustion_time: Notifies when you are about to run out of SLO budget within a specified number of hours.budget_rate: Notifies when budget drops by at least a specified percentage within a defined time window.Required when alert_type is exhaustion_time.
Must not be specified when alert_type is budget_rate.
Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached.
A list of Recipients to notify when an alert fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
{ "id": "fS7vfB81Wcy", "description": "Use this runbook if this alert fires.", "triggered": false, "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-31T15:08:11Z", "alert_type": "exhaustion_time", "exhaustion_minutes": 120, "slo": { "id": "2LBq9LckbcA" }, "recipients": [ { … } ] }
curl -i -X GET \
'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}?slo_id=string' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description of the Burn Alert.
Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.
The ISO8601-formatted time when the Burn Alert was created.
The ISO8601-formatted time when the Burn Alert was updated.
One of the supported alert types:
exhaustion_time: Notifies when you are about to run out of SLO budget within a specified number of hours.budget_rate: Notifies when budget drops by at least a specified percentage within a defined time window.Required when alert_type is exhaustion_time.
Must not be specified when alert_type is budget_rate.
Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached.
[ { "id": "fS7vfB81Wcy", "alert_type": "exhaustion_time", "description": "Use this runbook (link) if this alert fires.", "triggered": true, "exhaustion_minutes": 120, "slo": { … }, "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-22T17:32:11Z" }, { "id": "gT7wgC82Xcz", "alert_type": "budget_rate", "description": "Use this runbook (link) if this alert fires.", "triggered": true, "budget_rate_window_minutes": 60, "budget_rate_decrease_threshold_per_million": 1000, "slo": { … }, "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-22T17:32:11Z" } ]
curl -i -X GET \
'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}/{burnAlertId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description of the Burn Alert.
Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.
The ISO8601-formatted time when the Burn Alert was created.
The ISO8601-formatted time when the Burn Alert was updated.
One of the supported alert types:
exhaustion_time: Notifies when you are about to run out of SLO budget within a specified number of hours.budget_rate: Notifies when budget drops by at least a specified percentage within a defined time window.Required when alert_type is exhaustion_time.
Must not be specified when alert_type is budget_rate.
Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached.
A list of Recipients to notify when an alert fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
{ "id": "fS7vfB81Wcy", "description": "Use this runbook if this alert fires.", "triggered": false, "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-31T15:08:11Z", "alert_type": "exhaustion_time", "exhaustion_minutes": 120, "slo": { "id": "2LBq9LckbcA" }, "recipients": [ { … } ] }
A description of the Burn Alert.
One of the supported alert types:
exhaustion_time: Notifies when you are about to run out of SLO budget within a specified number of hours.budget_rate: Notifies when budget drops by at least a specified percentage within a defined time window.Required when alert_type is exhaustion_time.
Must not be specified when alert_type is budget_rate.
Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached.
A list of Recipients to notify when an alert fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
One of the supported Recipient Types
The target of the notification. For example, the specific Slack channel or email address. For Recipients of type = "webhook" or type = "msteams_workflow", this will be the Name in the UI and webhook_name in the Recipients API. Deprecated: Use the Recipients API first, then pass the Recipient ID.
curl -i -X PUT \
'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}/{burnAlertId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"description": "Use this runbook if this alert fires.",
"alert_type": "exhaustion_time",
"exhaustion_minutes": 120,
"recipients": [
{
"id": "abcd123",
"type": "email",
"target": "alerts@example.com"
}
]
}'Success
A description of the Burn Alert.
Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.
The ISO8601-formatted time when the Burn Alert was created.
The ISO8601-formatted time when the Burn Alert was updated.
One of the supported alert types:
exhaustion_time: Notifies when you are about to run out of SLO budget within a specified number of hours.budget_rate: Notifies when budget drops by at least a specified percentage within a defined time window.Required when alert_type is exhaustion_time.
Must not be specified when alert_type is budget_rate.
Amount of time (in minutes) left until your projected SLO budget is exhausted. The alert will fire when this exhaustion threshold is reached.
A list of Recipients to notify when an alert fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
{ "id": "fS7vfB81Wcy", "description": "Use this runbook if this alert fires.", "triggered": false, "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-31T15:08:11Z", "alert_type": "exhaustion_time", "exhaustion_minutes": 120, "slo": { "id": "2LBq9LckbcA" }, "recipients": [ { … } ] }
curl -i -X DELETE \
'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}/{burnAlertId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Team cannot access management APIs.
{ "error": "Your team has been denied access to Management APIs, please contact support to be unblocked." }
Type of the data that the Column will contain.
If true, the column is excluded from autocomplete and raw data field lists.
curl -i -X POST \
'https://api.honeycomb.io/1/columns/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"key_name": "my_column",
"type": "integer",
"description": "An integer column",
"hidden": false
}'Success
Type of the data that the Column will contain.
If true, the column is excluded from autocomplete and raw data field lists.
ISO8601 formatted time the column was last written to (received event data).
{ "id": "yUheCUmgZ8p", "key_name": "my_column", "hidden": false, "description": "An integer column", "type": "integer", "last_written": "2022-07-26T22:38:05Z", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z" }
curl -i -X GET \
'https://api.honeycomb.io/1/columns/{datasetSlug}?key_name=string' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'When listing all columns, an array of Column objects will be returned. When using key_name, will return a single Column object if found.
Type of the data that the Column will contain.
If true, the column is excluded from autocomplete and raw data field lists.
ISO8601 formatted time the column was last written to (received event data).
Lists all columns.
[ { "id": "yUheCUmgZ8p", "key_name": "my_column", "hidden": false, "description": "", "type": "integer", "last_written": "2022-07-26T22:38:05Z", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z" }, { "id": "yUheCUmgZ8q", "key_name": "other_column", "hidden": false, "description": "", "type": "string", "last_written": "2022-07-26T22:38:05Z", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z" } ]
curl -i -X GET \
'https://api.honeycomb.io/1/columns/{datasetSlug}/{columnId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
Type of the data that the Column will contain.
If true, the column is excluded from autocomplete and raw data field lists.
ISO8601 formatted time the column was last written to (received event data).
{ "id": "yUheCUmgZ8p", "key_name": "my_column", "hidden": false, "description": "", "type": "integer", "last_written": "2022-07-26T22:38:05Z", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z" }
Type of the data that the Column will contain.
If true, the column is excluded from autocomplete and raw data field lists.
curl -i -X PUT \
'https://api.honeycomb.io/1/columns/{datasetSlug}/{columnId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"key_name": "my_column",
"type": "integer",
"description": "An integer column",
"hidden": false
}'Success
Type of the data that the Column will contain.
If true, the column is excluded from autocomplete and raw data field lists.
ISO8601 formatted time the column was last written to (received event data).
{ "id": "yUheCUmgZ8p", "key_name": "my_column", "hidden": false, "description": "", "type": "string", "last_written": "2022-07-26T22:38:05Z", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/columns/{datasetSlug}/{columnId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'{ "status": 400, "type": "https://api.honeycomb.io/problems/unparseable", "title": "The request body could not be parsed.", "error": "invalid gzip data" }
The dataset will be created within the environment associated with your API key.
A description for the dataset.
curl -i -X POST \
https://api.honeycomb.io/1/datasets \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "string",
"description": "A nice description of my dataset",
"expand_json_depth": 3
}'OK - Dataset already exists
A description for the dataset.
The maximum unpacking depth of nested JSON fields.
The total number of unique fields for this Dataset. The value will be null if the dataset does not contain any fields yet.
The ISO8601-formatted time when the dataset last received event data. The value will be null if no data has been received yet.
{ "name": "My Dataset!", "description": "A nice description of my dataset", "settings": { "delete_protected": true }, "expand_json_depth": 3, "slug": "my-dataset-", "regular_columns_count": 100, "last_written_at": "2022-07-21T18:39:23Z", "created_at": "2022-09-22T17:32:11Z" }
curl -i -X GET \
https://api.honeycomb.io/1/datasets \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description for the dataset.
The maximum unpacking depth of nested JSON fields.
The total number of unique fields for this Dataset. The value will be null if the dataset does not contain any fields yet.
The ISO8601-formatted time when the dataset last received event data. The value will be null if no data has been received yet.
The ISO8601-formatted time when the dataset was created.
[ { "name": "my dataset!", "description": "my dataset described!", "slug": "my-dataset-", "expand_json_depth": 2, "created_at": "2022-07-21T18:39:23Z", "last_written_at": "2022-07-22T19:52:00Z", "regular_columns_count": 12 }, { "name": "another dataset", "description": "", "slug": "another-dataset", "expand_json_depth": 0, "created_at": "2022-07-21T18:39:23Z", "last_written_at": "2022-07-22T19:52:00Z", "regular_columns_count": 98 } ]
curl -i -X GET \
'https://api.honeycomb.io/1/datasets/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description for the dataset.
The maximum unpacking depth of nested JSON fields.
The total number of unique fields for this Dataset. The value will be null if the dataset does not contain any fields yet.
The ISO8601-formatted time when the dataset last received event data. The value will be null if no data has been received yet.
{ "name": "My Dataset!", "description": "A nice description of my dataset", "settings": { "delete_protected": true }, "expand_json_depth": 3, "slug": "my-dataset-", "regular_columns_count": 100, "last_written_at": "2022-07-21T18:39:23Z", "created_at": "2022-09-22T17:32:11Z" }
Deletes the Dataset. This is an irreversible operation. It may take several minutes for the deletion process to complete.
WARNING: This endpoint will allow anyone with an API key that has the manage dataset permission to delete any dataset in the environment (or any dataset in the whole team for Classic customers).
Datasets with Deletion Protection enabled cannot be deleted.
To delete a Dataset with Deletion Protection enabled, first disable Deletion Protection by updating the Dataset with settings.delete_protected = false.
curl -i -X DELETE \
'https://api.honeycomb.io/1/datasets/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Update a Dataset's settings. All fields must be specified, as omitting one will have the effect of reverting the setting to the default.
A description for the dataset.
The maximum unpacking depth of nested JSON fields.
curl -i -X PUT \
'https://api.honeycomb.io/1/datasets/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"expand_json_depth": 3,
"description": "my updated description",
"settings": {
"delete_protected": false
}
}'Updated
A description for the dataset.
The maximum unpacking depth of nested JSON fields.
The total number of unique fields for this Dataset. The value will be null if the dataset does not contain any fields yet.
The ISO8601-formatted time when the dataset last received event data. The value will be null if no data has been received yet.
{ "name": "My Dataset!", "slug": "my-dataset-", "description": "my updated description", "settings": { "delete_protected": false }, "expand_json_depth": 3, "created_at": "2022-07-21T18:39:23Z", "last_written_at": "2022-09-22T17:32:03Z", "regular_columns_count": 100 }
Dataset definitions describe the fields with special meaning in the Dataset.
Refer to the Dataset Definitions documentation for more information.
Honeycomb automatically creates these Dataset definition fields when the Dataset is created. Manual creation of Dataset definitions is not needed.
The PATCH payload takes a map of Dataset definition type to Dataset definition. Fields not defined in the request are not modified on the server. Note: In order to CLEAR a column of a Dataset definition set the column’s name field to an empty string.
The Parent Span ID - The ID of this span's parent span, the call location the current span was called from.
Metadata: Kind - The kind of Span. For example, client or server. The use of this field to identify Span Events and Links is deprecated. Use the field Metadata: Annotation Type.
Metadata: Annotation Type - The type of span annotation. For example, span_event or link. This lets Honeycomb visualize this type of event differently in a trace. Do not use this field for other purposes.
Metadata: Link Span ID - Links let you tie traces and spans to one another. The Link Span ID lets you link to a different span (when used with Link Trace ID).
Metadata: Link Trace ID - Links let you tie traces and spans to one another. The Link Trace Id lets you link to a different trace or a different span in the same trace (when used with Link Span ID).
Severity level of the event (also known as log level). Supported values: trace, debug, info, warn, error, fatal, unspecified.
curl -i -X PATCH \
'https://api.honeycomb.io/1/dataset_definitions/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"duration_ms": {
"name": "duration_we_send",
"column_type": "derived_column"
}
}'Dataset Definitions have been updated
The Parent Span ID - The ID of this span's parent span, the call location the current span was called from.
Metadata: Kind - The kind of Span. For example, client or server. The use of this field to identify Span Events and Links is deprecated. Use the field Metadata: Annotation Type.
Metadata: Annotation Type - The type of span annotation. For example, span_event or link. This lets Honeycomb visualize this type of event differently in a trace. Do not use this field for other purposes.
Metadata: Link Span ID - Links let you tie traces and spans to one another. The Link Span ID lets you link to a different span (when used with Link Trace ID).
Metadata: Link Trace ID - Links let you tie traces and spans to one another. The Link Trace Id lets you link to a different trace or a different span in the same trace (when used with Link Span ID).
Severity level of the event (also known as log level). Supported values: trace, debug, info, warn, error, fatal, unspecified.
{ "duration_ms": { "name": "duration_ms", "column_type": "column" }, "error": null, "name": null, "parent_id": null, "route": null, "service_name": null, "span_id": { "name": "my_span_id", "column_type": "column" }, "span_kind": null, "annotation_type": null, "link_trace_id": null, "link_span_id": null, "status": null, "trace_id": null, "user": null, "log_severity": null, "log_message": null }
curl -i -X GET \
'https://api.honeycomb.io/1/dataset_definitions/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
The Parent Span ID - The ID of this span's parent span, the call location the current span was called from.
Metadata: Kind - The kind of Span. For example, client or server. The use of this field to identify Span Events and Links is deprecated. Use the field Metadata: Annotation Type.
Metadata: Annotation Type - The type of span annotation. For example, span_event or link. This lets Honeycomb visualize this type of event differently in a trace. Do not use this field for other purposes.
Metadata: Link Span ID - Links let you tie traces and spans to one another. The Link Span ID lets you link to a different span (when used with Link Trace ID).
Metadata: Link Trace ID - Links let you tie traces and spans to one another. The Link Trace Id lets you link to a different trace or a different span in the same trace (when used with Link Span ID).
Severity level of the event (also known as log level). Supported values: trace, debug, info, warn, error, fatal, unspecified.
{ "duration_ms": { "name": "duration_ms", "column_type": "column" }, "error": null, "name": null, "parent_id": null, "route": null, "service_name": null, "span_id": { "name": "my_span_id", "column_type": "column" }, "span_kind": null, "annotation_type": null, "link_trace_id": null, "link_span_id": null, "status": null, "trace_id": null, "user": null, "log_severity": null, "log_message": null }
Derived columns allow you to run queries based on the value of an expression that is derived from the columns in an event.
This API allows you to list, create, update, and delete derived columns in a dataset or across a whole environment, paralleling the behavior of the Schema tab within a Dataset's or Environment's Settings UI.
The human-readable name of the derived column, as it will be referenced when building queries.
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.
curl -i -X POST \
'https://api.honeycomb.io/1/derived_columns/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"alias": "string",
"expression": "string",
"description": ""
}'Success
The human-readable name of the derived column, as it will be referenced when building queries.
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.
A human-readable description for the derived column that displays in the UI.
{ "id": "yUheCUmgZ8p", "alias": "one", "description": "just one", "expression": "INT(1)", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-11-16T17:34:01Z" }
curl -i -X GET \
'https://api.honeycomb.io/1/derived_columns/{datasetSlug}?alias=string' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'When listing all columns, an array of DerivedColumn objects will be returned. When using key_name, will return a single DerivedColumn object if found.
The human-readable name of the derived column, as it will be referenced when building queries.
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.
A human-readable description for the derived column that displays in the UI.
[]
curl -i -X GET \
'https://api.honeycomb.io/1/derived_columns/{datasetSlug}/{derivedColumnId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
The human-readable name of the derived column, as it will be referenced when building queries.
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.
A human-readable description for the derived column that displays in the UI.
{ "id": "yUheCUmgZ8p", "alias": "one", "description": "just one", "expression": "INT(1)", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-11-16T17:34:01Z" }
The human-readable name of the derived column, as it will be referenced when building queries.
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.
curl -i -X PUT \
'https://api.honeycomb.io/1/derived_columns/{datasetSlug}/{derivedColumnId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"alias": "string",
"expression": "string",
"description": ""
}'Success
The human-readable name of the derived column, as it will be referenced when building queries.
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.
A human-readable description for the derived column that displays in the UI.
{ "id": "string", "alias": "string", "expression": "string", "description": "", "created_at": "string", "updated_at": "string" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/derived_columns/{datasetSlug}/{derivedColumnId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'{ "status": 400, "type": "https://api.honeycomb.io/problems/unparseable", "title": "The request body could not be parsed.", "error": "invalid gzip data" }
The Events API endpoints are the lowest-level way to send Events to Honeycomb. This should be your last resort!
If unsure where to start when instrumenting an application, read about how to Send Data to Honeycomb.
If you are building a tracing or metrics library, we recommend using OpenTelemetry.
Supports batch creation of events.
Dataset names are case insensitive. POST requests to "MyDatasET" will land in the same dataset as "mydataset". Names may contain URL-encoded spaces or other special characters, but not URL-encoded slashes. For example, "My%20Dataset" will show up in the UI as "My Dataset".
The first event received for a dataset determines the casing of the displayed name. All subsequent variations in casing will use the originally specified case.
The array should contain one or more JSON objects representing Events. Each Event contains its payload under the data key. Values of time and/or samplerate can be included as well.
The JSON payload should have the structure:
[{ "data": { "key1": "value1", "key2": 2.0 } }, ... ]
Size limitations may be addressed by compressing request bodies with gzip or zstd compression.
An empty 202 response indicates that the event has been queued for processing.
curl -i -X POST \
'https://api.honeycomb.io/1/batch/{datasetSlug}' \
-H 'Content-Encoding: gzip' \
-H 'Content-Type: application/octet-stream' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d string[ { "status": 202 }, { "status": 400, "error": "Request body should not be empty." }, { "status": 400, "error": "Event has too many columns." }, { "status": 400, "error": "Request body is malformed and cannot be read." } ]
The request body is limited to raw (potentially compressed) size of 100KB.
The maximum number of distinct columns (fields) allowed in an event is 2000.
A collection of key-value properties that represent the Event. Honeycomb supports basic data types for the values of each Event attribute.
curl -i -X POST \
'https://api.honeycomb.io/1/events/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Event-Time: 0' \
-H 'X-Honeycomb-Samplerate: 0' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"method": "GET",
"endpoint": "/foo",
"shard": "users",
"duration_ms": 32
}'The body is empty, or blank.
{ "error": "Request body should not be empty." }
The Kinesis Events API endpoints allow Honeycomb to process streaming events from Amazon Kinesis.
Refer to the Honeycomb AWS integrations documentation for more information.
The request body expected from Amazon Kinesis Firehose. Events and metrics have the same shape but the base64 encoded data blob for metrics is expected to be Protowire-encoded as well. CloudWatch Logs data coming through Amazon Kinesis Firehose is expected to have a gzip Content-Encoding.
curl -i -X POST \
'https://api.honeycomb.io/1/kinesis_events/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Amz-Firehose-Access-Key: YOUR_API_KEY_HERE' \
-H 'X-Amz-Firehose-Request-Id: string' \
-d '{
"requestId": "string",
"timestamp": 0,
"records": [
{
"data": "string"
}
]
}'{ "requestId": "string", "timestamp": 0, "errorMessage": "string" }
The marker body can include as many of the Marker fields as desired.
Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
Groups similar Markers. For example, deploys. All Markers of the same type appear with the same color on the graph. Refer to the Marker Settings API for altering the color of each type.
curl -i -X POST \
'https://api.honeycomb.io/1/markers/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"start_time": 1471040808,
"end_time": 1668453920,
"message": "backend deploy #123",
"type": "deploy",
"url": "http://link-to-build.here"
}'Created
Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
Groups similar Markers. For example, deploys. All Markers of the same type appear with the same color on the graph. Refer to the Marker Settings API for altering the color of each type.
A target for the marker. Clicking the marker text will take you to this URL.
{ "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" }
curl -i -X GET \
'https://api.honeycomb.io/1/markers/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
Groups similar Markers. For example, deploys. All Markers of the same type appear with the same color on the graph. Refer to the Marker Settings API for altering the color of each type.
A target for the marker. Clicking the marker text will take you to this URL.
Color can be assigned to Markers using the Marker Settings endpoint. This field will be populated when List All Markers is called.
[ { "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" }, { "created_at": "2016-08-14T05:39:42Z", "updated_at": "2016-08-14T05:39:42Z", "start_time": 1471040808, "message": "frontend deploy #123", "type": "deploy", "id": "c2b52fa0" } ]
If an existing field is not included in the payload, it will be erased.
Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
Groups similar Markers. For example, deploys. All Markers of the same type appear with the same color on the graph. Refer to the Marker Settings API for altering the color of each type.
curl -i -X PUT \
'https://api.honeycomb.io/1/markers/{datasetSlug}/{markerId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"start_time": 1471040808,
"end_time": 1668453920,
"message": "backend deploy #123",
"type": "deploy",
"url": "http://link-to-build.here"
}'Updated
Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
Groups similar Markers. For example, deploys. All Markers of the same type appear with the same color on the graph. Refer to the Marker Settings API for altering the color of each type.
A target for the marker. Clicking the marker text will take you to this URL.
{ "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" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/markers/{datasetSlug}/{markerId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success The deleted Marker will be in the body of the response.
Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
Groups similar Markers. For example, deploys. All Markers of the same type appear with the same color on the graph. Refer to the Marker Settings API for altering the color of each type.
A target for the marker. Clicking the marker text will take you to this URL.
{ "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" }
Groups similar Markers. For example, 'deploys'. All Markers of the same type appears with the same color on the graph.
curl -i -X POST \
'https://api.honeycomb.io/1/marker_settings/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"type": "deploy",
"color": "#7b1fa2"
}'Success
Groups similar Markers. For example, 'deploys'. All Markers of the same type appears with the same color on the graph.
Color to use for display of this marker type. Specified as hexadecimal RGB. For example, "#F96E11".
The ISO8601-formatted time when the Marker Setting was created.
{ "type": "deploy", "color": "#7b1fa2", "id": "gwAHiE5TS4j", "created_at": "2022-09-15T05:39:42Z", "updated_at": "2022-12-15T04:25:14Z" }
curl -i -X GET \
'https://api.honeycomb.io/1/marker_settings/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
Groups similar Markers. For example, 'deploys'. All Markers of the same type appears with the same color on the graph.
Color to use for display of this marker type. Specified as hexadecimal RGB. For example, "#F96E11".
The ISO8601-formatted time when the Marker Setting was created.
The ISO8601-formatted time when the Marker Setting was updated.
[ { "type": "deploy", "color": "#7b1fa2", "id": "gwAHiE5TS4j", "created_at": "2022-09-15T05:39:42Z", "updated_at": "2022-12-15T04:25:14Z" } ]
Groups similar Markers. For example, 'deploys'. All Markers of the same type appears with the same color on the graph.
curl -i -X PUT \
'https://api.honeycomb.io/1/marker_settings/{datasetSlug}/{id}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"type": "deploy",
"color": "#1fa297"
}'Success
Groups similar Markers. For example, 'deploys'. All Markers of the same type appears with the same color on the graph.
Color to use for display of this marker type. Specified as hexadecimal RGB. For example, "#F96E11".
The ISO8601-formatted time when the Marker Setting was created.
{ "type": "deploy", "color": "#1fa297", "id": "gwAHiE5TS4j", "created_at": "2022-09-15T05:39:42Z", "updated_at": "2022-12-20T08:10:05Z" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/marker_settings/{datasetSlug}/{id}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'the columns by which to break events down into groups
the calculations to return as a time series and summary table
set to "OR" to match ANY filter in the filter list
The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/10).
The terms on which to order the query results. Each term must appear in either the breakdowns field or the calculations field.
The maximum number of unique groups returned in 'results'. Aggregating many unique groups across a large time range is computationally expensive, and too high a limit with too many unique groups may cause queries to fail completely. Limiting the results to only the needed values can significantly speed up queries. The normal allowed maximum value when creating a query is 1_000. When running 'disable_series' queries, this can be overridden to be up to 10_000, so the maximum value returned from the API when fetching a query may be up to 10_000.
Absolute start time of query, in seconds since UNIX epoch. Must be <= end_time.
Time range of query in seconds. Can be used with either start_time (seconds after start_time), end_time (seconds before end_time), or without either (seconds before now).
curl -i -X POST \
'https://api.honeycomb.io/1/queries/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}'Success
the columns by which to break events down into groups
the calculations to return as a time series and summary table
set to "OR" to match ANY filter in the filter list
The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/10).
The terms on which to order the query results. Each term must appear in either the breakdowns field or the calculations field.
The maximum number of unique groups returned in 'results'. Aggregating many unique groups across a large time range is computationally expensive, and too high a limit with too many unique groups may cause queries to fail completely. Limiting the results to only the needed values can significantly speed up queries. The normal allowed maximum value when creating a query is 1_000. When running 'disable_series' queries, this can be overridden to be up to 10_000, so the maximum value returned from the API when fetching a query may be up to 10_000.
Absolute start time of query, in seconds since UNIX epoch. Must be <= end_time.
Time range of query in seconds. Can be used with either start_time (seconds after start_time), end_time (seconds before end_time), or without either (seconds before now).
{ "id": "abc3419d", "calculations": [ { … } ], "orders": [ { … } ], "time_range": 7200 }
curl -i -X GET \
'https://api.honeycomb.io/1/queries/{datasetSlug}/{queryId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
the columns by which to break events down into groups
the calculations to return as a time series and summary table
set to "OR" to match ANY filter in the filter list
The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/10).
The terms on which to order the query results. Each term must appear in either the breakdowns field or the calculations field.
The maximum number of unique groups returned in 'results'. Aggregating many unique groups across a large time range is computationally expensive, and too high a limit with too many unique groups may cause queries to fail completely. Limiting the results to only the needed values can significantly speed up queries. The normal allowed maximum value when creating a query is 1_000. When running 'disable_series' queries, this can be overridden to be up to 10_000, so the maximum value returned from the API when fetching a query may be up to 10_000.
Absolute start time of query, in seconds since UNIX epoch. Must be <= end_time.
Time range of query in seconds. Can be used with either start_time (seconds after start_time), end_time (seconds before end_time), or without either (seconds before now).
{ "id": "abc3419d", "breakdowns": [ "user_agent" ], "calculations": [ { … } ], "orders": [ { … } ], "limit": 10, "time_range": 7200, "end_time": 1676467828 }
A description of the Query.
curl -i -X POST \
'https://api.honeycomb.io/1/query_annotations/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "My Named Query",
"description": "A nice description of My Named Query",
"query_id": "mabAMpSPDjH"
}'Created
A description of the Query.
The ID of the Query that the annotation describes. Note: Once created, it is NOT possible to change the query ID associated with an annotation. It is possible to have multiple annotations associated with a Query.
ISO8601 formatted time when the Query Annotation was created.
{ "name": "My Named Query", "description": "A nice description of My Named Query", "query_id": "mabAMpSPDjH", "id": "sGUnkBHgRFN", "created_at": "2022-10-26T21:36:04Z", "updated_at": "2022-12-04T08:14:26Z" }
curl -i -X GET \
'https://api.honeycomb.io/1/query_annotations/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description of the Query.
The ID of the Query that the annotation describes. Note: Once created, it is NOT possible to change the query ID associated with an annotation. It is possible to have multiple annotations associated with a Query.
ISO8601 formatted time when the Query Annotation was created.
ISO8601 formatted time when the Query Annotation was updated.
[ { "name": "My Named Query", "description": "A nice description of My Named Query", "query_id": "mabAMpSPDjH", "id": "sGUnkBHgRFN", "created_at": "2022-10-26T21:36:04Z", "updated_at": "2022-12-04T08:14:26Z" } ]
curl -i -X GET \
'https://api.honeycomb.io/1/query_annotations/{datasetSlug}/{queryAnnotationId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A description of the Query.
The ID of the Query that the annotation describes. Note: Once created, it is NOT possible to change the query ID associated with an annotation. It is possible to have multiple annotations associated with a Query.
ISO8601 formatted time when the Query Annotation was created.
{ "name": "My Named Query", "description": "A nice description of My Named Query", "query_id": "mabAMpSPDjH", "id": "sGUnkBHgRFN", "created_at": "2022-10-26T21:36:04Z", "updated_at": "2022-12-04T08:14:26Z" }
A description of the Query.
curl -i -X PUT \
'https://api.honeycomb.io/1/query_annotations/{datasetSlug}/{queryAnnotationId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "My Updated Annotation",
"description": "A nice description of My Update Annotation",
"query_id": "mabAMpSPDjH",
"id": "sGUnkBHgRFN",
"created_at": "2022-10-26T21:36:04Z",
"updated_at": "2022-12-16T10:44:08Z"
}'Success
A description of the Query.
The ID of the Query that the annotation describes. Note: Once created, it is NOT possible to change the query ID associated with an annotation. It is possible to have multiple annotations associated with a Query.
ISO8601 formatted time when the Query Annotation was created.
{ "name": "My Updated Annotation", "description": "A nice description of My Update Annotation", "query_id": "mabAMpSPDjH" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/query_annotations/{datasetSlug}/{queryAnnotationId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'This feature is available as part of the Honeycomb Enterprise plan.
Query Results are the aggregated data from a Query, similar to what is displayed in graphs or heatmaps within the Honeycomb UI. Receiving results from a Query is a three-step process:
Create the Query (or Query Spec), which validates that the query parameters are valid. Creating a query does not actually run the query to get results. Run the query asynchronously by creating a Query Result referencing the Query’s ID. This returns a Query Result ID. Poll the query result endpoint (with the Query Result ID) until the data is ready.
Note that many Query Results can be created from a single Query. This is particularly useful when using a relative time_range parameter in the Query. For example, a Query with time_range: 7200 and no explicit start_time or end_time can be re-run over and over, with each resulting Query Result containing the most recent 2 hours of data. This is conceptually similar to clicking Run Query in the Honeycomb UI without changing any query parameters.
IMPORTANT API RESTRICTIONS:
To ensure the stability of Honeycomb systems, we have enabled the following API restrictions. These restrictions may change over time.
Query Results can only be created for events with timestamps within the past 7 days.
When creating a Query Result, the time ranges from the Query are truncated according to the following rules. For queries with a time range of:
less than or equal to 6 hours, results are truncated to the nearest 1 minute. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:28:00Z.
greater than 6 hours and less than or equal to 2 days, results are truncated to the nearest 5 minutes. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:25:00Z.
greater than 2 days and less than or equal to 7 days, results are truncated to the nearest 30 minutes. For example, a start/end time of 2021-04-22T05:28:12Z will be truncated to 2021-04-22T05:00:00Z.
Creating a Query Result is rate limited to 10 requests per minute. Status code 429 will be returned when rate limited.
Query Results cannot take longer than 10 seconds to run.
Kick off processing of a Query to then get back the Query Results. Once the Query Result has been created, the query will be run asynchronously, allowing the result data to be fetched from the GET query result endpoint. Only the last 7 days of data can be queried. Any queries with a start_time, end_time, or time_range older than last 7 days will result in a 400 error response.
The ID of a query returned from the Queries endpoint.
If true, will disable calculation and return of the full time-series data, usually included in the 'series' response field, instead only returning the summarized 'results'.
If 'disable_series' is true, then a limit may optionally be given, which will override the limit normally associated with the query. Unlike normal query results which are limited to 1_000 results, 'disable_series' results may have a limit of up to 10_000. If 'disable_series' is false, then this field will be ignored.
curl -i -X POST \
'https://api.honeycomb.io/1/query_results/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"query_id": "mabAMpSPDjH",
"disable_series": true,
"limit": 10000
}'{ "query": { "calculations": [ … ], "orders": [ … ], "limit": 10000, "time_range": 7200 }, "complete": false, "id": "dfg456", "links": { "query_url": "https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456", "graph_image_url": "https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456/snapshot" } }
Get the Query Result details for a specific Query Result ID. This endpoint is used to fetch the results of a query that had previously been created. It is recommended to follow the Location header included in the Create Query Result output, but the URL can also be constructed manually with the <query-result-id>.
curl -i -X GET \
'https://api.honeycomb.io/1/query_results/{datasetSlug}/{queryResultId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified.
Indicates if the query results are available yet or not. For example, is the query still being processed or complete?
{ "query": { "calculations": [ … ], "orders": [ … ], "limit": 10000, "time_range": 7200 }, "complete": true, "id": "dfg456", "data": { "series": [], "results": [ … ] }, "links": { "query_url": "https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456", "graph_image_url": "https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/dfg456/snapshot" } }
Unlike many resources, Recipients are not linked to a specific Environment or Dataset. The Recipient will be created for the Team associated with your API key. The details fields will vary depending on the type of Recipient. Use the drop-down to view the specific fields for each type value. Before Slack Recipients can be created, the Slack OAuth flow in the Integration Center must be completed.
One of the supported Recipient Types
curl -i -X POST \
https://api.honeycomb.io/1/recipients \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"type": "pagerduty",
"details": {
"pagerduty_integration_name": "Example PagerDuty Service",
"pagerduty_integration_key": "7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK"
}
}'Success
ISO8601 formatted time the Recipient was created.
ISO8601 formatted time the Recipient was updated.
One of the supported Recipient Types
{ "id": "yUheCUmgZ8p", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z", "type": "pagerduty", "details": { "pagerduty_integration_name": "Example PagerDuty Service", "pagerduty_integration_key": "7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK" } }
curl -i -X GET \
https://api.honeycomb.io/1/recipients \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
ISO8601 formatted time the Recipient was created.
ISO8601 formatted time the Recipient was updated.
One of the supported Recipient Types
[ { "id": "yUheCUmgZ8p", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z", "type": "pagerduty", "details": { … } } ]
curl -i -X GET \
'https://api.honeycomb.io/1/recipients/{recipientId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
ISO8601 formatted time the Recipient was created.
ISO8601 formatted time the Recipient was updated.
One of the supported Recipient Types
{ "id": "yUheCUmgZ8p", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z", "type": "pagerduty", "details": { "pagerduty_integration_name": "Example PagerDuty Service", "pagerduty_integration_key": "7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK" } }
Update a Recipient by specifying the recipient ID and full recipient details. (Partial PUT is not supported.) Updates to the Recipient Type is not supported. For example, changing an existing Recipient from PagerDuty to Email is not allowed. Important: Modifying an existing recipient will change the destination of all triggers/burn alerts that use that recipient.
One of the supported Recipient Types
curl -i -X PUT \
'https://api.honeycomb.io/1/recipients/{recipientId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"type": "pagerduty",
"details": {
"pagerduty_integration_name": "Example PagerDuty Service",
"pagerduty_integration_key": "7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK"
}
}'Success
ISO8601 formatted time the Recipient was created.
ISO8601 formatted time the Recipient was updated.
One of the supported Recipient Types
{ "id": "yUheCUmgZ8p", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z", "type": "pagerduty", "details": { "pagerduty_integration_name": "Example PagerDuty Service", "pagerduty_integration_key": "7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK" } }
curl -i -X DELETE \
'https://api.honeycomb.io/1/recipients/{recipientId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'{ "error": "unknown API key - check your credentials" }
This feature is available as part of the Honeycomb Pro and Enterprise plans.
Honeycomb SLOs allow you to define and monitor Service Level Objectives (SLOs) for your organization.
This API allows you to list, create, update, and delete SLO objects.
A nice description of the SLO's intent and context.
Reference to the Derived Column used as the indicator of event success.
The time period, in days, over which the SLO will be evaluated.
curl -i -X POST \
'https://api.honeycomb.io/1/slos/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "My SLO",
"description": "SLO to ensure requests succeed and are fast",
"sli": {
"alias": "error_sli"
},
"time_period_days": 30,
"target_per_million": 990000
}'Success - SLO created
A nice description of the SLO's intent and context.
Reference to the Derived Column used as the indicator of event success.
The time period, in days, over which the SLO will be evaluated.
The number of events out of one million (1,000,000) that you expected qualified events to succeed.
The ISO8601-formatted time the SLO was last reset. The value will be null if the SLO has not yet been reset.
The ISO8601-formatted time when the SLO was created.
{ "id": "string", "name": "My SLO", "description": "SLO to ensure requests succeed and are fast", "sli": { "alias": "error_sli" }, "time_period_days": 30, "target_per_million": 990000, "reset_at": "2022-011-11T09:53:04Z", "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-31T15:08:11Z" }
curl -i -X GET \
'https://api.honeycomb.io/1/slos/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A nice description of the SLO's intent and context.
Reference to the Derived Column used as the indicator of event success.
The time period, in days, over which the SLO will be evaluated.
The number of events out of one million (1,000,000) that you expected qualified events to succeed.
The ISO8601-formatted time the SLO was last reset. The value will be null if the SLO has not yet been reset.
The ISO8601-formatted time when the SLO was created.
The ISO8601-formatted time when the SLO was updated.
[ { "id": "string", "name": "My SLO", "description": "SLO to ensure requests succeed and are fast", "sli": { … }, "time_period_days": 30, "target_per_million": 990000, "reset_at": "2022-011-11T09:53:04Z", "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-31T15:08:11Z" } ]
Allows SLO reporting data (budget_remaining and compliance) to be returned when retrieving a single SLO. This feature is available as part of the Honeycomb Enterprise plan.
curl -i -X GET \
'https://api.honeycomb.io/1/slos/{datasetSlug}/{sloId}?detailed=true' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A nice description of the SLO's intent and context.
Reference to the Derived Column used as the indicator of event success.
The time period, in days, over which the SLO will be evaluated.
The number of events out of one million (1,000,000) that you expected qualified events to succeed.
The ISO8601-formatted time the SLO was last reset. The value will be null if the SLO has not yet been reset.
The ISO8601-formatted time when the SLO was created.
Get an SLO by ID
{ "id": "bZ1aRHAUsjG", "name": "My SLO", "description": "My SLO description", "sli": { "alias": "my-sli" }, "time_period_days": 30, "target_per_million": 989900, "reset_at": "2022-10-15T13:53:11Z", "created_at": "2022-09-15T05:39:42Z", "updated_at": "2022-12-20T08:10:05Z" }
Partial updates are not supported.
A nice description of the SLO's intent and context.
Reference to the Derived Column used as the indicator of event success.
The time period, in days, over which the SLO will be evaluated.
curl -i -X PUT \
'https://api.honeycomb.io/1/slos/{datasetSlug}/{sloId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "My SLO",
"description": "SLO to ensure requests succeed and are fast",
"sli": {
"alias": "error_sli"
},
"time_period_days": 30,
"target_per_million": 990000
}'Success
A nice description of the SLO's intent and context.
Reference to the Derived Column used as the indicator of event success.
The time period, in days, over which the SLO will be evaluated.
The number of events out of one million (1,000,000) that you expected qualified events to succeed.
The ISO8601-formatted time the SLO was last reset. The value will be null if the SLO has not yet been reset.
The ISO8601-formatted time when the SLO was created.
{ "id": "string", "name": "My SLO", "description": "SLO to ensure requests succeed and are fast", "sli": { "alias": "error_sli" }, "time_period_days": 30, "target_per_million": 990000, "reset_at": "2022-011-11T09:53:04Z", "created_at": "2022-09-22T17:32:11Z", "updated_at": "2022-10-31T15:08:11Z" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/slos/{datasetSlug}/{sloId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Triggers let you receive notifications when your data in Honeycomb crosses the thresholds that you configure. The graph on which to alert is as flexible as a Honeycomb query, which helps reduce false positives due to known errors.Triggers fire
This API allows you to list, create, update, and delete Triggers.
curl -i -X GET \
'https://api.honeycomb.io/1/triggers/{datasetSlug}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'OK
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
If true, the trigger has crossed its specified threshold without resolving.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
[ { "id": "string", "name": "string", "description": "string", "threshold": { … }, "frequency": 0, "alert_type": "on_change", "disabled": false, "triggered": true, "recipients": [ … ], "evaluation_schedule_type": "frequency", "evaluation_schedule": { … }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "query": {}, "query_id": "string" } ]
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
curl -i -X POST \
'https://api.honeycomb.io/1/triggers/{datasetSlug}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "string",
"description": "string",
"threshold": {
"op": ">",
"value": 0,
"exceeded_limit": 1
},
"frequency": 0,
"alert_type": "on_change",
"disabled": false,
"recipients": [
{
"id": "string",
"type": "pagerduty",
"target": "string",
"details": {
"pagerduty_severity": "critical"
}
}
],
"evaluation_schedule_type": "frequency",
"evaluation_schedule": {
"window": {
"days_of_week": [
"sunday"
],
"start_time": "14:00",
"end_time": "21:00"
}
},
"query": {}
}'Success - trigger created
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
If true, the trigger has crossed its specified threshold without resolving.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
{ "id": "string", "name": "string", "description": "string", "threshold": { "op": ">", "value": 0, "exceeded_limit": 1 }, "frequency": 0, "alert_type": "on_change", "disabled": false, "triggered": true, "recipients": [ { … } ], "evaluation_schedule_type": "frequency", "evaluation_schedule": { "window": { … } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "query": {}, "query_id": "string" }
curl -i -X GET \
'https://api.honeycomb.io/1/triggers/{datasetSlug}/{triggerId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
If true, the trigger has crossed its specified threshold without resolving.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
{ "id": "string", "name": "string", "description": "string", "threshold": { "op": ">", "value": 0, "exceeded_limit": 1 }, "frequency": 0, "alert_type": "on_change", "disabled": false, "triggered": true, "recipients": [ { … } ], "evaluation_schedule_type": "frequency", "evaluation_schedule": { "window": { … } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "query": {}, "query_id": "string" }
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
curl -i -X PUT \
'https://api.honeycomb.io/1/triggers/{datasetSlug}/{triggerId}' \
-H 'Content-Type: application/json' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE' \
-d '{
"name": "string",
"description": "string",
"threshold": {
"op": ">",
"value": 0,
"exceeded_limit": 1
},
"frequency": 0,
"alert_type": "on_change",
"disabled": false,
"recipients": [
{
"id": "string",
"type": "pagerduty",
"target": "string",
"details": {
"pagerduty_severity": "critical"
}
}
],
"evaluation_schedule_type": "frequency",
"evaluation_schedule": {
"window": {
"days_of_week": [
"sunday"
],
"start_time": "14:00",
"end_time": "21:00"
}
},
"query": {},
"query_id": "string"
}'Success
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
If true, the trigger has crossed its specified threshold without resolving.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
{ "id": "string", "name": "string", "description": "string", "threshold": { "op": ">", "value": 0, "exceeded_limit": 1 }, "frequency": 0, "alert_type": "on_change", "disabled": false, "triggered": true, "recipients": [ { … } ], "evaluation_schedule_type": "frequency", "evaluation_schedule": { "window": { … } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "query": {}, "query_id": "string" }
curl -i -X DELETE \
'https://api.honeycomb.io/1/triggers/{datasetSlug}/{triggerId}' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'curl -i -X GET \
'https://api.honeycomb.io/1/recipients/{recipientId}/triggers' \
-H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'Success
A short, human-readable name for this Trigger, which will be displayed in the UI and when the trigger fires.
The threshold over which the trigger will fire, specified as both an operator and a value.
The interval in seconds in which to check the results of the query’s calculation against the threshold. Cannot be more than 4 times the query's duration (i.e. duration <= frequency*4). See A Caveat on Time for more information on specifying a query's duration. minimum: 60 maximum: 86400 multipleOf: 60 default: 900
How often to fire an alert when a trigger threshold is crossed.
on_change sends a trigger notification when the result of the specified calculation crosses the threshold. The trigger resolves only when the result of the query no longer satisfies the threshold condition.on_true keeps sending a trigger notification at current frequency when and while the threshold is met. (This reflects the same behavior as the "Send an alert every time a threshold is met" checkbox in the Honeycomb UI.)If true, the trigger will not be evaluated and alerts will not be sent.
If true, the trigger has crossed its specified threshold without resolving.
A list of Recipients to notify when the Trigger fires. Using type+target is deprecated. First, create the Recipient via the Recipients API, and then specify the ID.
The schedule type used by the trigger. The default is frequency, where the trigger runs at the specified frequency. The window type means that the trigger will run at the specified frequency, but only in the time window specified in the evaluation_schedule field.
A schedule that determines when the trigger is run. When the time is within the scheduled window, the trigger will be run at the specified frequency. Outside of the window, the trigger will not be run.
[ { "id": "string", "name": "string", "description": "string", "threshold": { … }, "frequency": 0, "alert_type": "on_change", "disabled": false, "triggered": true, "recipients": [ … ], "evaluation_schedule_type": "frequency", "evaluation_schedule": { … }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "query": {}, "query_id": "string" } ]