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.
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.
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.
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 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.
The Kinesis Events API endpoints allow Honeycomb to process streaming events from Amazon Kinesis.
Refer to the Honeycomb AWS integrations documentation for more information.
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.
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.
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" } ]