A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Honeycomb API is how an app or AI agent works with a Honeycomb account: sending telemetry events to a dataset, running a query, building a board, and setting a trigger or an SLO that watches the data. Access is granted through an API key, where the key type and the permissions it carries set what a call can do, from an ingest key that only sends events to a configuration key that manages an environment to a management key that works across a team. Honeycomb does not push events; instead a trigger or burn alert notifies a registered recipient when monitored data crosses a threshold.
How an app or AI agent connects to Honeycomb determines what it can reach. There is a route for sending telemetry, a route for managing the resources in an environment, a team-level route for managing keys and environments, and a hosted server that exposes Honeycomb tools to agents, and each is governed by the key behind it and the permissions that key carries.
The v1 API handles event ingestion and the resources inside an environment, like queries, boards, triggers, SLOs, datasets, and columns. It answers at https://api.honeycomb.io in the US and https://api.eu1.honeycomb.io in the EU, takes and returns JSON, and authenticates with an Ingest Key or a Configuration Key in the X-Honeycomb-Team header.
The v2 API handles team-level management, like API keys and environments. It uses the JSON:API content type application/vnd.api+json, authenticates with a Management Key sent as an Authorization Bearer token, and pages through lists with a cursor.
Honeycomb does not push raw events. A Trigger or a Burn Alert sends a notification to a registered recipient when a threshold is crossed or an SLO budget burns down. Recipients can be Email, Slack, PagerDuty, Microsoft Teams, or a webhook URL.
Honeycomb's hosted Model Context Protocol server lets an agent query traces, metrics, and logs, check the state of triggers and SLOs, and create boards through natural language. It authenticates with OAuth or an API key, and is offered to one-click clients like Cursor, VS Code, and Claude Desktop. A self-hosted version exists at github.com/honeycombio/honeycomb-mcp but is deprecated in favor of the hosted server.
An Ingest Key sends telemetry data to one environment. It carries a single permission, whether it may implicitly create a dataset when an event names one that does not exist, and that permission cannot be changed after the key is created. It is passed in the X-Honeycomb-Team header as the Key ID and Secret joined with no separator.
A Configuration Key manages the resources in one environment. It carries granular permissions chosen at creation, like Send Events, Manage Queries and Columns, Manage Triggers, Manage SLOs, Manage Markers, Manage Public Boards, Create Datasets, and Run Queries. Its Token value is passed in the X-Honeycomb-Team header.
A Management Key works at the team level across all environments, and is required by the v2 API for managing API keys and environments. It is sent in the Authorization header as a Bearer token, with the Key ID and Secret joined by a colon.
The Honeycomb API is split into areas an agent can act on, like events, queries, boards, triggers, SLOs, and datasets. Each area has its own methods and its own permissions, and some grant access to far more than others.
Send a single telemetry event, or send a batch of events, to a dataset.
List, create, update, and delete the markers that flag points in time on a graph, like deploys.
List, read, create, update, and delete the triggers that notify recipients when data crosses a threshold.
List, read, create, update, and delete the boards that collect saved queries and panels.
Create and read a saved query specification, and run a query to get its results.
List, read, create, update, and delete service level objectives and the burn alerts that watch their budget.
List, read, create, update, and delete the datasets that hold events.
List, read, create, update, and delete the columns in a dataset and the calculated fields derived from them.
List, read, create, update, and delete the API keys for a team, through the team-level v2 management API.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
EventsSend a single telemetry event, or send a batch of events, to a dataset.2 | ||||||
| POST | /1/events/{datasetSlug} | Send a single telemetry event to a dataset. Recommended only for testing; batches are far more efficient. | write | Send Events | Current | |
Best sent with an Ingest Key. A Configuration Key works if it has the Send Events permission. Acts onevent Permission (capability) Send EventsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/batch/{datasetSlug} | Send a batch of telemetry events to a dataset in one request. | write | Send Events | Current | |
The preferred way to send events. Best sent with an Ingest Key; a Configuration Key works if it has the Send Events permission. Acts onevent Permission (capability) Send EventsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MarkersList, create, update, and delete the markers that flag points in time on a graph, like deploys.4 | ||||||
| GET | /1/markers/{datasetSlug} | List all markers in a dataset, or across the environment with __all__. | read | Manage Markers | Current | |
Configuration Key with the Manage Markers permission. Acts onmarker Permission (capability) Manage MarkersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/markers/{datasetSlug} | Create a marker on a dataset, or on the whole environment with __all__, to flag a point in time like a deploy. | write | Manage Markers | Current | |
Configuration Key with the Manage Markers permission. Acts onmarker Permission (capability) Manage MarkersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/markers/{datasetSlug}/{markerId} | Update an existing marker. | write | Manage Markers | Current | |
Configuration Key with the Manage Markers permission. Acts onmarker Permission (capability) Manage MarkersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/markers/{datasetSlug}/{markerId} | Delete a marker. | write | Manage Markers | Current | |
Configuration Key with the Manage Markers permission. Acts onmarker Permission (capability) Manage MarkersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TriggersList, read, create, update, and delete the triggers that notify recipients when data crosses a threshold.5 | ||||||
| GET | /1/triggers/{datasetSlug} | List all triggers in a dataset, or across the environment with __all__. | read | Manage Triggers | Current | |
Configuration Key with the Manage Triggers permission. Acts ontrigger Permission (capability) Manage TriggersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/triggers/{datasetSlug}/{triggerId} | Get a single trigger. | read | Manage Triggers | Current | |
Configuration Key with the Manage Triggers permission. Acts ontrigger Permission (capability) Manage TriggersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/triggers/{datasetSlug} | Create a trigger that notifies recipients when a query crosses a threshold. The query can be inline or referenced by id. | write | Manage Triggers | Current | |
Configuration Key with the Manage Triggers permission. Recipients can be Email, Slack, PagerDuty, Microsoft Teams, or a webhook. Acts ontrigger Permission (capability) Manage TriggersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/triggers/{datasetSlug}/{triggerId} | Update a trigger, including its threshold and recipients. | write | Manage Triggers | Current | |
Configuration Key with the Manage Triggers permission. Acts ontrigger Permission (capability) Manage TriggersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/triggers/{datasetSlug}/{triggerId} | Delete a trigger. | write | Manage Triggers | Current | |
Configuration Key with the Manage Triggers permission. Acts ontrigger Permission (capability) Manage TriggersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BoardsList, read, create, update, and delete the boards that collect saved queries and panels.5 | ||||||
| GET | /1/boards | List all boards in the environment. | read | Manage Public Boards | Current | |
Configuration Key with the Manage Public Boards permission. Acts onboard Permission (capability) Manage Public BoardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/boards/{boardId} | Get a single board. | read | Manage Public Boards | Current | |
Configuration Key with the Manage Public Boards permission. Acts onboard Permission (capability) Manage Public BoardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/boards | Create a board. Legacy classic boards are no longer accepted; new boards use the flexible panel layout. | write | Manage Public Boards | Current | |
Configuration Key with the Manage Public Boards permission. A create call with type classic now fails. Acts onboard Permission (capability) Manage Public BoardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/boards/{boardId} | Update a board, including its panels. | write | Manage Public Boards | Current | |
Configuration Key with the Manage Public Boards permission. Acts onboard Permission (capability) Manage Public BoardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/boards/{boardId} | Delete a board. | write | Manage Public Boards | Current | |
Configuration Key with the Manage Public Boards permission. Acts onboard Permission (capability) Manage Public BoardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Queries & query resultsCreate and read a saved query specification, and run a query to get its results.4 | ||||||
| POST | /1/queries/{datasetSlug} | Create a saved query specification. It is not run; the returned id is used by boards and triggers. | write | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. Use __all__ for an environment-wide query. Acts onquery Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/queries/{datasetSlug}/{queryId} | Get a saved query specification by id. | read | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. Acts onquery Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/query_results/{datasetSlug} | Run a query to produce a result. The result is fetched separately once it is ready. | write | Run Queries | Current | |
Enterprise plan only. Needs the Manage Queries and Columns and Run Queries permissions on a Configuration Key. Acts onquery_result Permission (capability) Run QueriesVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per minute (1 per minute with relational fields) SourceOfficial documentation ↗ | ||||||
| GET | /1/query_results/{datasetSlug}/{queryResultId} | Get the result of a query that was run, including its data once it is complete. | read | Run Queries | Current | |
Enterprise plan only. Needs the Manage Queries and Columns and Run Queries permissions on a Configuration Key. Acts onquery_result Permission (capability) Run QueriesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SLOs & burn alertsList, read, create, update, and delete service level objectives and the burn alerts that watch their budget.7 | ||||||
| GET | /1/slos/{datasetSlug} | List all SLOs in a dataset, or across the environment with __all__. | read | Manage SLOs | Current | |
Configuration Key with the Manage SLOs permission. Acts onslo Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/slos/{datasetSlug}/{sloId} | Get a single SLO, optionally with its current budget and compliance. | read | Manage SLOs | Current | |
Configuration Key with the Manage SLOs permission. Acts onslo Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/slos/{datasetSlug} | Create an SLO on a dataset to track a service level objective. | write | Manage SLOs | Current | |
Configuration Key with the Manage SLOs permission. Acts onslo Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /1/slos/{datasetSlug}/{sloId} | Update an SLO. | write | Manage SLOs | Current | |
Configuration Key with the Manage SLOs permission. Acts onslo Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/slos/{datasetSlug}/{sloId} | Delete an SLO. | write | Manage SLOs | Current | |
Configuration Key with the Manage SLOs permission. Acts onslo Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/burn_alerts/{datasetSlug} | Create a burn alert that notifies recipients when an SLO is burning through its error budget. | write | Manage SLOs | Current | |
Burn alerts are part of the SLOs API and use the Manage SLOs permission. Acts onburn_alert Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/burn_alerts/{datasetSlug} | List all burn alerts for an SLO. | read | Manage SLOs | Current | |
Filtered by the SLO id passed as a query parameter. Uses the Manage SLOs permission. Acts onburn_alert Permission (capability) Manage SLOsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DatasetsList, read, create, update, and delete the datasets that hold events.3 | ||||||
| GET | /1/datasets | List all datasets in the environment. | read | Manage Datasets | Current | |
Configuration Key with a dataset permission. Acts ondataset Permission (capability) Manage DatasetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/datasets/{datasetSlug} | Get a single dataset by slug. | read | Manage Datasets | Current | |
Configuration Key with a dataset permission. Acts ondataset Permission (capability) Manage DatasetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/datasets | Create a dataset, or return the existing one if the name or slug already matches. | write | Create Datasets | Current | |
Configuration Key with the Create Datasets permission. Acts ondataset Permission (capability) Create DatasetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Columns & derived columnsList, read, create, update, and delete the columns in a dataset and the calculated fields derived from them.5 | ||||||
| GET | /1/columns/{datasetSlug} | List all columns in a dataset, or across the environment with __all__. | read | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. An optional key_name parameter filters to one column. Acts oncolumn Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/columns/{datasetSlug} | Create a column in a dataset. | write | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. Acts oncolumn Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1/columns/{datasetSlug}/{columnId} | Delete a column from a dataset. | write | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. Acts oncolumn Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/derived_columns/{datasetSlug} | Create a calculated field, also called a derived column, from an expression over a dataset's fields. | write | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. Acts onderived_column Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/derived_columns/{datasetSlug} | List all calculated fields in a dataset, or across the environment. | read | Manage Queries and Columns | Current | |
Configuration Key with the Manage Queries and Columns permission. Acts onderived_column Permission (capability) Manage Queries and ColumnsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
API keysList, read, create, update, and delete the API keys for a team, through the team-level v2 management API.5 | ||||||
| GET | /2/teams/{teamSlug}/api-keys | List all API keys for a team, through the team-level v2 management API. | read | Management Key | Current | |
A v2 endpoint. Authenticates with a Management Key sent as Authorization Bearer, and uses the JSON:API content type. Cursor-paginated. Acts onapi_key Permission (capability) Management KeyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /2/teams/{teamSlug}/api-keys/{keyId} | Get a single API key, either an ingest key or a configuration key, by id. | read | Management Key | Current | |
A v2 endpoint. Authenticates with a Management Key sent as Authorization Bearer. Acts onapi_key Permission (capability) Management KeyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/teams/{teamSlug}/api-keys | Create an API key for a team, such as an ingest or configuration key with chosen permissions. | write | Management Key | Current | |
A v2 endpoint. Authenticates with a Management Key. The secret of the new key is returned once, at creation. Acts onapi_key Permission (capability) Management KeyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /2/teams/{teamSlug}/api-keys/{keyId} | Update an API key, such as disabling it or renaming it. | write | Management Key | Current | |
A v2 endpoint. Authenticates with a Management Key. Acts onapi_key Permission (capability) Management KeyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /2/teams/{teamSlug}/api-keys/{keyId} | Delete an API key, revoking its access. | write | Management Key | Current | |
A v2 endpoint. Authenticates with a Management Key. Acts onapi_key Permission (capability) Management KeyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Honeycomb does not push events to an integration. Instead, a Trigger or a Burn Alert sends a notification to a registered recipient, like a Slack channel, an email address, or a webhook URL, when monitored data crosses a threshold or an SLO burns through its budget.
| Event | What it signals | Triggered by |
|---|
Honeycomb limits how fast an app or AI agent can call, through a per-team request quota measured over a short window, with stricter limits on a few heavy endpoints like running a query.
Honeycomb meters requests per team over a short rolling window, and reports the state in response headers: a RateLimit header gives limit, remaining, and reset in seconds, and a RateLimit-Policy header gives the request count and window, for example 100 requests per 60 seconds. A few endpoints are far stricter: running a query through Create Query Result is limited to 10 requests per minute, and 1 per minute when the query uses relational fields. Exceeding a limit returns HTTP 429; most 429 responses carry a Retry-After header, except the Events, Batch Events, and Query Data APIs.
Cursor-based pagination applies to the v2 list endpoints, like List all API Keys and List all Environments. The page[size] parameter sets the page size, defaulting to 20 and capping at 100, and page[after] takes the opaque cursor from the previous response's links.next field. Pagination ends when links.next is null. Cursors are opaque and should be passed through, not parsed. The v1 list endpoints return their full set without a cursor.
A request may be at most 100,000 bytes, and exceeding it returns 413 Payload Too Large, so large telemetry should be split across batches. The v1 API takes and returns application/json, while the v2 API uses the JSON:API content type application/vnd.api+json.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request body could not be parsed or is invalid. | Fix the request body and resend. |
| 401 | Unauthorized | The API key is missing or invalid. | Send a valid key in the right header for the API version, the X-Honeycomb-Team header for v1 or an Authorization Bearer token for v2. |
| 403 | Forbidden | The key is valid but does not carry the permission this operation needs. | Grant the missing permission on the key, such as Manage Triggers or Run Queries, or use a key type that allows the call. |
| 404 | Not Found | The requested resource does not exist, or the key cannot see it. | Confirm the dataset slug and resource id, and that the key reaches that environment. |
| 409 | Conflict | The request conflicts with the current state, such as a duplicate name. | Use a different name, or update the existing resource instead of creating it. |
| 413 | Payload Too Large | The request exceeds the maximum size of 100,000 bytes. | Send fewer events per batch, or split the request. |
| 415 | Unsupported Media Type | The Content-Type header does not match what the endpoint expects: application/json for v1 and application/vnd.api+json for v2. | Set the Content-Type header to the value the API version expects. |
| 422 | Validation Failed | The request was well-formed but a field held an invalid value. The body carries a type_detail array naming each failed field with a code like invalid, missing, incorrect_type, or already_exists. | Read the type_detail array, correct the named fields, and resend. |
| 429 | Rate Limited | The request rate exceeded the per-team quota. A v1 response uses the RFC 7807 problem format, and a v2 response uses a JSON:API errors array with code rate-limited/may-retry. | Back off and retry, using the Retry-After header where present and the RateLimit header to pace requests. |
| 500 | Internal Server Error | An unexpected error occurred on Honeycomb's side. | Retry with backoff, and contact Honeycomb support if it persists. |
Honeycomb versions its API by path prefix rather than by a dated version string. The v1 API covers event ingestion and the resources inside an environment, and a newer v2 API covers team-level management like API keys and environments.
Honeycomb versions its API by path prefix rather than a dated version string. The v1 prefix covers event ingestion and the resources inside an environment, and the v2 prefix covers team-level management. New resources are added under the prefix that fits, so an existing integration is not forced to migrate, and breaking changes are communicated through the API changelog rather than a version bump.
The Boards API stopped accepting legacy classic boards. From 15 August 2025 a create call with type classic, or with the type omitted, fails, and on 29 August 2025 any remaining legacy boards were automatically migrated to flexible boards. New boards use the flexible panel layout with a layout_generation field set to manual or auto.
Honeycomb announced a hosted Model Context Protocol server that lets an AI agent query traces, metrics, and logs, check triggers and SLOs, and create boards. It authenticates with OAuth or an API key and offers one-click setup for clients like Cursor, VS Code, and Claude Desktop.
Honeycomb made its Management API generally available, letting teams programmatically manage configuration like queries, datasets, derived columns, boards, triggers, and SLOs, the foundation the v1 resource endpoints and later the v2 key and environment endpoints build on.
An integration calls the prefix it needs and is not forced to migrate when new resources are added.
Honeycomb API changelog ↗Bollard AI sits between a team's AI agents and Honeycomb. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.