Maintainers
Pricing
Enterprise
More
More
Documentation
Try Live
Rankings
Install
Blog
Docs7
Ask
New
Add Docs
Honeycomb API
https://docs.honeycomb.io/api/
Admin
The API allows programmatic management of many resources within Honeycomb.
Tokens:
313,088
Snippets:
2,422
Trust Score:
10
Update:
3 months ago
Context
Chat
Benchmark
81.9
Latest
Show doc for...
Code
Info
Show Results
Tokens:
Raw
Copy
Link
Tokens:
Raw
Copy
Link
### Not Found Response Example (JSON) Source: https://docs.honeycomb.io/api/burn-alerts/create-a-burn-alert Example of a JSON response when a requested resource, such as a dataset, is not found. ```json { "error": "dataset not found" } ``` -------------------------------- ### RateLimit Header Example Source: https://docs.honeycomb.io/api/events/create-events Example of the RateLimit header, indicating request limits and reset times. Format: 'limit=X, remaining=Y, reset=Z'. ```yaml RateLimit: description: | The (draft07) recommended header from the IETF on rate limiting. The value of the header is formatted "limit=X, remaining=Y, reset=Z". Where: - X is the maximum number of requests allowed in the window - Y is the number of requests remaining in the window - Z is the number of seconds until the limit resets schema: type: string example: limit=100, remaining=50, reset=60 ``` -------------------------------- ### RateLimitPolicy Header Example Source: https://docs.honeycomb.io/api/events/create-events Example of the RateLimitPolicy header, specifying the request limit and window size. Format: 'X;w=Y'. ```yaml RateLimitPolicy: description: | The (draft07) recommended header from the IETF on rate limiting. The value of the header is formatted "X;w=Y". Where: - X is the maximum number of requests allowed in a window - Y is the size of the window in seconds schema: type: string example: 100;w=60 ``` -------------------------------- ### Example Denied Access Error Source: https://docs.honeycomb.io/api/slos/get-all-slos This example shows the structure of an error response when a team is denied access to management APIs. ```yaml error: >- Your team has been denied access to Management APIs, please contact support to be unblocked. ``` -------------------------------- ### API Key Authentication Header Example Source: https://docs.honeycomb.io/api/auth This example shows how to format the `X-Honeycomb-Team` header for authentication. The value should be your Honeycomb Configuration Key or the Token from the UI. ```http X-Honeycomb-Team: 1234567890123456789012 ``` -------------------------------- ### RateLimit Header Example Source: https://docs.honeycomb.io/api/events/create-an-event Example of the RateLimit header, formatted according to IETF draft07, indicating the request limit, remaining requests, and reset time. ```string limit=100, remaining=50, reset=60 ``` -------------------------------- ### RateLimitPolicy Header Example Source: https://docs.honeycomb.io/api/events/create-an-event Example of the RateLimitPolicy header, formatted according to IETF draft07, specifying the request limit and the window size in seconds. ```string 100;w=60 ``` -------------------------------- ### Not Found Response Example (Problem+JSON) Source: https://docs.honeycomb.io/api/burn-alerts/create-a-burn-alert Example of a Problem+JSON response when a requested resource is not found, including status, type, title, and detail. ```json { "status": 404, "type": "https://api.honeycomb.io/problems/not-found", "title": "The requested resource cannot be found.", "error": "Dataset not found", "detail": "Dataset not found" } ``` -------------------------------- ### NotFound Response Example Source: https://docs.honeycomb.io/api/events/create-events Example response for a not found request. Includes rate limiting headers and can return different error formats. ```yaml NotFound: description: Not Found headers: Ratelimit: $ref: '#/components/headers/RateLimit' RateLimitPolicy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: dataset not found application/problem+json: schema: $ref: '#/components/schemas/DetailedError' example: status: 404 type: https://api.honeycomb.io/problems/not-found title: The requested resource cannot be found. error: Dataset not found detail: Dataset not found application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' ``` -------------------------------- ### Dataset Not Found Error Example Source: https://docs.honeycomb.io/api/datasets/update-a-dataset This example shows the structure of an error response when a dataset is not found. It includes details about the error and potential headers like RateLimit. ```json { "error": "dataset not found" } ``` ```json { "status": 404, "type": "https://api.honeycomb.io/problems/not-found", "title": "The requested resource cannot be found.", "error": "Dataset not found", "detail": "Dataset not found" } ``` ```json { "errors": [ { "id": "06dcdd6508ca822f0e7e2bb4121c1f52", "code": "rate-limited/may-retry", "title": "request rate limit exceeded", "detail": "Please try again after 2025-02-01T15:23:12Z." } ] } ``` -------------------------------- ### Simple Query Response Example Source: https://docs.honeycomb.io/api/queries This is an example of a successful response from a simple Honeycomb API query. It includes a unique query ID and the results of the specified calculations and ordering. ```json { "id": "abc3419d", "calculations": [ { "op": "COUNT" } ], "orders": [ { "op": "COUNT", "order": "descending" } ], "time_range": 7200 } ``` -------------------------------- ### Get SLO Realtime Counts Source: https://docs.honeycomb.io/api/slos/get-slo-realtime-counts Fetches the current realtime counts for an SLO. This endpoint is useful for monitoring the SLO's status within the current hour. Note that realtime counts reset at the start of each hour. ```APIDOC ## GET /api/v0/organizations/{organization_id}/datasets/{dataset_id}/slos/{slo_id}/realtime_counts ### Description Retrieves the current realtime counts for a specific SLO within the current hour. Realtime counts accumulate from the start of each hour and reset at hour boundaries. For completed hours, use the Get SLO Hourly Counts History endpoint. ### Method GET ### Endpoint /api/v0/organizations/{organization_id}/datasets/{dataset_id}/slos/{slo_id}/realtime_counts ### Query Parameters - **start_time** (integer) - Required - Unix timestamp (seconds) indicating the start of the time range. Must be greater than `start_time` and within the same clock hour as `start_time`. - **end_time** (integer) - Required - Unix timestamp (seconds) indicating the end of the time range. Must be greater than `start_time` and within the same clock hour as `start_time`. ### Responses #### Success Response (200) - **slo_id** (string) - The unique identifier of the SLO. - **resolution_seconds** (integer) - The width of each window in seconds. Always `60`. - **epoch** (string) - A hash of the SLO's SLI expression and dataset configuration. This value changes whenever the SLO definition changes in a way that affects count computation. - **period_start** (integer) - Unix timestamp of the start of the current accumulation period (the most recent hour boundary). - **windows** (array) - Ordered list of per-minute count windows within the requested time range. - **window_start** (integer) - Unix timestamp of the start of the window. - **window_end** (integer) - Unix timestamp of the end of the window. - **total_count** (integer) - The total number of events in the window. - **error_count** (integer) - The number of error events in the window. - **is_partial** (boolean) - Indicates if the window is partial (i.e., not a full minute). #### Response Example (200) ```json { "slo_id": "bZ1aRHAUsjG", "resolution_seconds": 60, "epoch": "a3f9c2d1e8b74056", "period_start": 1745251200, "windows": [ { "window_start": 1745251200, "window_end": 1745251260, "total_count": 1243, "error_count": 3, "is_partial": false }, { "window_start": 1745251260, "window_end": 1745251320, "total_count": 1188, "error_count": 1, "is_partial": false }, { "window_start": 1745251320, "window_end": 1745251380, "total_count": 1301, "error_count": 0, "is_partial": true } ] } ``` #### Error Responses - **400** - Bad Request - **401** - Unauthorized - **403** - Forbidden - **404** - Not Found - **429** - Rate Limited - **default** - Generic Error ``` -------------------------------- ### Create a Flexible Board with Query and Text Panels Source: https://docs.honeycomb.io/api/boards/create-a-board Use this example to create a board with a manual layout, combining a query panel and a text panel. Ensure the query_id and query_annotation_id are valid. ```json { "name": "My API Board", "description": "A board created via the API with mixed panel types", "type": "flexible", "panels": [ { "type": "query", "query_panel": { "query_id": "abc1234e", "query_annotation_id": "e4c24a35" }, "position": { "x_coordinate": 0, "y_coordinate": 0, "height": 6, "width": 8 } }, { "type": "text", "text_panel": { "content": "# Welcome to our API Dashboard\n\nThis board shows key metrics for our services." }, "position": { "x_coordinate": 8, "y_coordinate": 0, "height": 3, "width": 4 } } ], "layout_generation": "manual", "tags": [ { "key": "team", "value": "backend" }, { "key": "environment", "value": "production" } ] } ``` -------------------------------- ### Create an Auto-Layout Board with Multiple Panel Types Source: https://docs.honeycomb.io/api/boards/create-a-board This example demonstrates creating a board that automatically generates its layout, incorporating query, SLO, and text panels. Specify the dataset for query panels and the slo_id for SLO panels. ```json { "name": "Service Health Overview", "description": "Comprehensive service monitoring dashboard", "type": "flexible", "panels": [ { "type": "query", "query_panel": { "query_id": "def5678f", "query_annotation_id": "a1b2c3d4", "dataset": "frontend-logs" } }, { "type": "slo", "slo_panel": { "slo_id": "BGfyxhFto" } }, { "type": "text", "text_panel": { "content": "## Service Status" } } ] } ``` -------------------------------- ### GenericError Example (application/json) Source: https://docs.honeycomb.io/api/columns/list-all-columns Example of a generic error response for invalid query data. ```json { "error": "invalid Query data" } ``` -------------------------------- ### DetailedError Example (application/problem+json) Source: https://docs.honeycomb.io/api/columns/list-all-columns Example of a detailed error response for unparseable request bodies. ```json { "status": 400, "type": "https://api.honeycomb.io/problems/unparseable", "title": "The request body could not be parsed.", "error": "invalid gzip data" } ``` -------------------------------- ### Update a Configuration Key Source: https://docs.honeycomb.io/api/key-management/update-an-api-key This example demonstrates updating a Configuration Key. You can modify its name, enabled status, and specific permissions. ```json { "data": { "id": "hcxlk_12345678901234567890123456", "type": "api-keys", "attributes": { "name": "updated name", "disabled": false, "permissions": { "create_datasets": true, "send_events": true, "manage_markers": true, "manage_triggers": true, "manage_boards": true, "run_queries": true, "manage_columns": true, "manage_slos": true, "manage_recipients": true, "manage_privateBoards": false, "read_service_maps": true, "visible_team_members": true } } } } ``` -------------------------------- ### Example Rate Limit Headers Source: https://docs.honeycomb.io/api/rate-limit These headers indicate your current rate limit status and policy. `RateLimit` shows limit, remaining requests, and reset time. `RateLimit-Policy` specifies the requests allowed per window size. ```text RateLimit: limit=100, remaining=80, reset=54 RateLimit-Policy: 100;w=60 ``` -------------------------------- ### Forbidden Response Example (JSON) Source: https://docs.honeycomb.io/api/burn-alerts/create-a-burn-alert Example of a JSON response when access to management APIs is denied. ```json { "error": ">-" Your team has been denied access to Management APIs, please contact support to be unblocked." } ``` -------------------------------- ### Unauthorized Response Example Source: https://docs.honeycomb.io/api/events/create-events Example response for an unauthorized request. It can return a generic JSON error or a JSONAPIError. ```yaml Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unknown API key - check your credentials application/vnd.api+json: schema: $ref: '#/components/schemas/JSONAPIError' ``` -------------------------------- ### Unauthorized Error Example (application/json) Source: https://docs.honeycomb.io/api/columns/list-all-columns Example of an unauthorized error response due to unknown API key. ```json { "error": "unknown API key - check your credentials" } ``` -------------------------------- ### JSONAPIError Example (application/vnd.api+json) Source: https://docs.honeycomb.io/api/columns/list-all-columns Example of a JSON:API formatted error response for unparseable request bodies. ```json { "errors": [ { "id": "06dcdd6508ca822f0e7e2bb4121c1f52", "code": "invalid", "title": "request body could not be parsed", "detail": "invalid gzip data" } ] } ``` -------------------------------- ### Create Events API Request Example Source: https://docs.honeycomb.io/api/events/create-events This example demonstrates how to send a batch of events to a dataset. Ensure your API key has the 'Write Service Maps' permission. Dataset names are case-insensitive. ```json [ { "time": "2006-01-02T15:04:05.99Z", "samplerate": 1, "data": { "method": "GET", "endpoint": "/foo", "shard": "users", "duration_ms": 32 } }, { "time": "2006-01-02T15:04:05.99Z", "data": { "some_other_key": "value", "duration_ms": 40 } } ] ``` -------------------------------- ### Rate Limited Response Example (JSON) Source: https://docs.honeycomb.io/api/burn-alerts/create-a-burn-alert Example of a JSON response when the client has exceeded the rate limit. ```json { "error": "Rate Limited" } ``` -------------------------------- ### Example Recipient Response Source: https://docs.honeycomb.io/api/recipients This is an example of a successful JSON response when listing recipients. It shows a PagerDuty recipient with its details. ```json [ { "type": "pagerduty", "id": "yUheCUmgZ8p", "created_at": "2022-07-26T22:38:04Z", "updated_at": "2022-07-26T22:38:04Z", "details": { "pagerduty_integration_name": "Example PagerDuty Service", "pagerduty_integration_key": "7zOwh1edS8xHGcwfb2bA4sqY8E6PJzSK" } } ] ``` -------------------------------- ### Honeycomb Ingest Key Header Example Source: https://docs.honeycomb.io/api/events/create-an-event Demonstrates how to pass an Ingest Key in the X-Honeycomb-Team header for authentication. Ensure the key is correctly formatted. ```http X-Honeycomb-Team: hc[x]ik_1234567890123456789012345612345678901234567890123456789012 ``` -------------------------------- ### Conflict Error Example (Problem+JSON) Source: https://docs.honeycomb.io/api/calculated-fields/update-a-calculated-field Example of a conflict error response using the Problem+JSON format, indicating a resource conflict. ```json { "status": 409, "type": "https://api.honeycomb.io/problems/conflict", "title": ">- Request could not be completed due to a conflict with the current state of the target resource. ", "error": "A resource by that name already exists." } ``` -------------------------------- ### Configuration Key Authentication Source: https://docs.honeycomb.io/api/events/create-an-event Demonstrates how to authenticate using a Honeycomb Configuration Key by passing the token in the 'X-Honeycomb-Team' header. ```http X-Honeycomb-Team: 1234567890123456789012 ```
