Create a Burn Alert

Honeycomb API (1.0.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.

https://docs.honeycomb.io

Download OpenAPI description

api.json

api.yaml

Overview

E-mail support@honeycomb.io

License Apache 2.0

Servers

https://api.honeycomb.io/

https://api.eu1.honeycomb.io/

Auth

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.

Operations

Boards

Boards are a place to pin and save useful queries and graphs you want to retain for later reuse and reference.

This API allows you to list, create, update, and delete Boards.

Operations

Burn Alerts

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.

Operations

Authorization

The API key must have the Manage SLOs permission. Learn more about API keys here.

Create a Burn Alert

Request

Create a Burn Alert in a specified dataset against a specified SLO.

Path

datasetSlugstringrequired

The dataset slug.

Bodyapplication/jsonrequired

Any of:

descriptionstring<= 1023 characters

A description of the Burn Alert.

Example: "Use this runbook if this alert fires."

alert_typestring

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.

Default "exhaustion_time"

Enum"exhaustion_time""budget_rate"

Example: "exhaustion_time"

exhaustion_minutesinteger>= 0

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.

Example: 120

sloobjectrequired

Details about the SLO associated with the burn alert.

Example: {"id":"2LBq9LckbcA"}

slo.idstringrequired

Unique identifier (ID) of a SLO.

Example: "2LBq9LckbcA"

recipientsArray of objects(NotificationRecipient)non-emptyrequired

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.

Example: [{"id":"abcd123","type":"email","target":"alerts@example.com"}]

recipients[].idstring

recipients[].detailsobject(NotificationRecipientDetails)

recipients[].typestringDeprecated

One of the supported Recipient Types

Enum"pagerduty""email""slack""webhook""msteams""msteams_workflow"

recipients[].targetstringDeprecated

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"
      }
    ]
  }'

Responses

Created

Bodyapplication/json

Any of:

idstringread-only

Unique identifier (ID) of a Burn alert.

Example: "fS7vfB81Wcy"

descriptionstring<= 1023 characters

A description of the Burn Alert.

Example: "Use this runbook if this alert fires."

triggeredbooleanread-only

Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.

Example: false

created_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was created.

Example: "2022-09-22T17:32:11Z"

updated_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was updated.

Example: "2022-10-31T15:08:11Z"

alert_typestring

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.

Default "exhaustion_time"

Enum"exhaustion_time""budget_rate"

Example: "exhaustion_time"

exhaustion_minutesinteger>= 0

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.

Example: 120

sloobject

Details about the SLO associated with the burn alert.

Example: {"id":"2LBq9LckbcA"}

recipientsArray of objects(NotificationRecipient)non-empty

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.

Example: [{"id":"abcd123","type":"email","target":"alerts@example.com"}]

Response

application/json

{
  "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": [
    { … }
  ]
}

List All Burn Alerts for an SLO

Request

Get all burn alerts associated with the SLO specified in the slo_id query param. It is not currently possible to retrieve all burn alerts for a dataset, environment, or team.

Path

datasetSlugstringrequired

The dataset slug.

Query

slo_idstringrequired

For use with the list endpoint to retrieve all burn alerts for a specified SLO.

curl -i -X GET \
  'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}?slo_id=string' \
  -H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/jsonArray [

Any of:

idstringread-only

Unique identifier (ID) of a Burn alert.

Example: "fS7vfB81Wcy"

descriptionstring<= 1023 characters

A description of the Burn Alert.

Example: "Use this runbook if this alert fires."

triggeredbooleanread-only

Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.

Example: false

created_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was created.

Example: "2022-09-22T17:32:11Z"

updated_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was updated.

Example: "2022-10-31T15:08:11Z"

alert_typestring

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.

Default "exhaustion_time"

Enum"exhaustion_time""budget_rate"

Example: "exhaustion_time"

exhaustion_minutesinteger>= 0

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.

Example: 120

sloobject

Details about the SLO associated with the burn alert.

Example: {"id":"2LBq9LckbcA"}

]

Response

application/json

[
  {
    "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"
  }
]

Get a Burn Alert

Request

Get a single Burn Alert by ID.

Path

datasetSlugstringrequired

The dataset slug.

burnAlertIdstringrequired

The unique identifier (ID) of a Burn Alert.

curl -i -X GET \
  'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}/{burnAlertId}' \
  -H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/json

Any of:

idstringread-only

Unique identifier (ID) of a Burn alert.

Example: "fS7vfB81Wcy"

descriptionstring<= 1023 characters

A description of the Burn Alert.

Example: "Use this runbook if this alert fires."

triggeredbooleanread-only

Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.

Example: false

created_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was created.

Example: "2022-09-22T17:32:11Z"

updated_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was updated.

Example: "2022-10-31T15:08:11Z"

alert_typestring

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.

Default "exhaustion_time"

Enum"exhaustion_time""budget_rate"

Example: "exhaustion_time"

exhaustion_minutesinteger>= 0

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.

Example: 120

sloobject

Details about the SLO associated with the burn alert.

Example: {"id":"2LBq9LckbcA"}

recipientsArray of objects(NotificationRecipient)non-empty

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.

Example: [{"id":"abcd123","type":"email","target":"alerts@example.com"}]

Response

application/json

{
  "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": [
    { … }
  ]
}

Update a Burn Alert

Request

Update a Burn Alert by specifying its ID and full details.

Path

datasetSlugstringrequired

The dataset slug.

burnAlertIdstringrequired

The unique identifier (ID) of a Burn Alert.

Bodyapplication/json

Any of:

descriptionstring<= 1023 characters

A description of the Burn Alert.

Example: "Use this runbook if this alert fires."

alert_typestring

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.

Default "exhaustion_time"

Enum"exhaustion_time""budget_rate"

Example: "exhaustion_time"

exhaustion_minutesinteger>= 0

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.

Example: 120

recipientsArray of objects(NotificationRecipient)non-emptyrequired

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.

Example: [{"id":"abcd123","type":"email","target":"alerts@example.com"}]

recipients[].idstring

recipients[].detailsobject(NotificationRecipientDetails)

recipients[].typestringDeprecated

One of the supported Recipient Types

Enum"pagerduty""email""slack""webhook""msteams""msteams_workflow"

recipients[].targetstringDeprecated

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"
      }
    ]
  }'

Responses

Success

Bodyapplication/json

Any of:

idstringread-only

Unique identifier (ID) of a Burn alert.

Example: "fS7vfB81Wcy"

descriptionstring<= 1023 characters

A description of the Burn Alert.

Example: "Use this runbook if this alert fires."

triggeredbooleanread-only

Indicates if the Burn Alert has been triggered. This field is read-only and is set to true when the alert is triggered.

Example: false

created_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was created.

Example: "2022-09-22T17:32:11Z"

updated_atstring(date-time)read-only

The ISO8601-formatted time when the Burn Alert was updated.

Example: "2022-10-31T15:08:11Z"

alert_typestring

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.

Default "exhaustion_time"

Enum"exhaustion_time""budget_rate"

Example: "exhaustion_time"

exhaustion_minutesinteger>= 0

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.

Example: 120

sloobject

Details about the SLO associated with the burn alert.

Example: {"id":"2LBq9LckbcA"}

recipientsArray of objects(NotificationRecipient)non-empty

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.

Example: [{"id":"abcd123","type":"email","target":"alerts@example.com"}]

Response

application/json

{
  "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": [
    { … }
  ]
}

Delete a Burn Alert

Request

Delete a Burn Alert by specifying its ID.

Path

datasetSlugstringrequired

The dataset slug.

burnAlertIdstringrequired

The unique identifier (ID) of a Burn Alert.

curl -i -X DELETE \
  'https://api.honeycomb.io/1/burn_alerts/{datasetSlug}/{burnAlertId}' \
  -H 'X-Honeycomb-Team: YOUR_API_KEY_HERE'

Responses

Success - no content

Response

Team cannot access management APIs.

{
  "error": "Your team has been denied access to Management APIs, please contact support to be unblocked."
}

Columns

Columns are fields in the events you send to Honeycomb.

This API allows you to list, create, update, and delete columns in a dataset.

Operations

Datasets

A Dataset represents a collection of related events that come from the same source, or are related to the same source.

This API allows you to list, create, and update datasets.

Operations

Dataset Definitions

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.

Operations

Derived Columns

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.

Operations

Events

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.

Operations

Environments

This API allows you to list, create, and update, and delete Environments.

Operations

Key Management

This API allows you to list, create, update, and delete API Keys for a Team.

Operations

Kinesis Events

The Kinesis Events API endpoints allow Honeycomb to process streaming events from Amazon Kinesis.

Refer to the Honeycomb AWS integrations documentation for more information.

Operations

Markers

Markers indicate points in time on graphs where interesting things happen, such as deploys or outages.

This API allows you to list, create, update, and delete Markers.

Operations

Marker Settings

Marker Settings apply to groups of similar Markers. For example, "deploys" markers appear with the same color on a graph.

This API allows you to list, create, update, and delete Marker Settings.

Operations

Queries

Queries in Honeycomb are specifications for queries, and are used to identify queries in other parts of the API - in particular: boards, triggers, and query annotations.

This API allows you to create and get query objects.

Operations

Query Annotations

Query Annotations in Honeycomb allow you to associate names and descriptions to queries to add additional information in collaboration features.

This API allows you to list, create, update, and delete Query Annotations.

Operations

Query Data

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.

Operations

Recipients

Honeycomb Recipients allow you to define and manage the Recipients that will get notified by a Trigger or Burn Alert.

The types of Recipients supported are: PagerDuty, Email, Webhook, Microsoft Teams, and Slack.

Operations

SLOs

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.

Operations

Triggers

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.

Operations

Errors

The Honeycomb API returns standardized error responses, as documented here.

Honeycomb API (1.0.0)

Auth

Boards

Burn Alerts

Authorization

Create a Burn Alert

Request

Responses

Was this helpful?

List All Burn Alerts for an SLO

Request

Responses

Was this helpful?

Get a Burn Alert

Request

Responses

Was this helpful?

Update a Burn Alert

Request

Responses

Was this helpful?

Delete a Burn Alert

Request

Responses

Was this helpful?

Columns

Datasets

Dataset Definitions

Derived Columns

Events

Environments

Key Management

Kinesis Events

Markers

Marker Settings

Queries

Query Annotations

Query Data

Recipients

SLOs

Triggers

Errors