Construct, save, and execute queries against the Honeycomb columnar store. Define breakdowns, calculations, filters, orders, and havings; persist a query as a reusable specification; trigger async execution via Query Data and poll for results. Query Annotations let you decorate saved queries with human-readable context. The Query Data API is the foundation for AI-assisted observability and Honeycomb MCP.
openapi: 3.1.0
info:
title: Honeycomb Queries API
version: 1.0.0
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
email: support@honeycomb.io
description: 'The API allows programmatic management of many resources within Honeycomb.
Please report any discrepancies with actual API behavior in <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb
Support</a>.
'
externalDocs:
url: https://docs.honeycomb.io
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Queries
description: '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.
## Authorization
The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
'
- name: Query Annotations
description: '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.
## Authorization
The API key must have the **Manage Queries and Columns** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).
'
- name: Query Data
description: "This feature is available as part of the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/).\n\nQuery 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:\n\nCreate 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.\nRun the query asynchronously by creating a Query Result referencing the Query\u2019s ID. This returns a Query Result ID.\nPoll the query result\
\ endpoint (with the Query Result ID) until the data is ready.\n\nNote 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.\nFor 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.\nThis is conceptually similar to clicking Run Query in the Honeycomb UI without changing any query parameters.\n\n**IMPORTANT API RESTRICTIONS:**\n\nTo ensure the stability of Honeycomb systems,\
\ we have enabled the following API restrictions. These restrictions may change over time.\n\n* Query Results can only be created for events with timestamps within the past 7 days.\n\n* 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:\n\n * 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.\n\n * 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.\n\n * 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.\n\n* Creating a Query Result is rate limited to 10 requests per\
\ minute. Status code 429 will be returned when rate limited.\n\n* Query Results cannot take longer than 10 seconds to run.\n\n* Creating a Query Result that contains Relational Fields is rate limited\
\ to 1 request per minute. Status code 429 will be returned when rate limited.\n\n * Query Results with Relational Fields may be more likely to take longer to run.\n\n* Regardless of whether the `compare_time_offset_seconds`\
\ field is populated on a query, query run responses will not include comparison results.\n\n## Authorization\n\nThe API key must have the **Manage Queries and Columns** and **Run Queries** permission.\
\ Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).\n"
paths:
/1/queries/{datasetSlug}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
post:
security:
- configuration_key: []
summary: Create a Query
description: 'Create a query from a specification. DOES NOT run the query to retrieve results.
'
tags:
- Queries
operationId: createQuery
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
examples:
Simple Query:
value:
calculations:
- op: COUNT
orders:
- op: COUNT
order: descending
time_range: 7200
Query With Filter and Group By:
value:
calculations:
- op: COUNT
breakdowns:
- user_agent
filters:
- op: '>='
column: response.status_code
value: 400
orders:
- op: COUNT
order: descending
time_range: 7200
Query With Filter and Calculated Fields:
value:
calculations:
- op: COUNT
breakdowns:
- response.status_code
filters:
- op: '='
column: adhoc_check
value: true
calculated_fields:
- name: adhoc_check
expression: GT($response.status_code, 200)
orders:
- op: COUNT
order: descending
time_range: 7200
Query With Relational Fields:
value:
calculations:
- op: COUNT
breakdowns:
- name
- root.response.status_code
filters:
- op: '='
column: child.response.status_code
value: 400
orders:
- op: COUNT
order: descending
time_range: 3600
compare_time_offset_seconds: 86400
required: true
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
examples:
Simple Query:
value:
id: abc3419d
calculations:
- op: COUNT
orders:
- op: COUNT
order: descending
time_range: 7200
Query With Filter and Group By:
value:
id: xyz321a
calculations:
- op: COUNT
breakdowns:
- user_agent
filters:
- op: '>='
column: response.status_code
value: 400
orders:
- op: COUNT
order: descending
time_range: 7200
Query With Filter and Calculated Fields:
value:
id: lmn098p
calculations:
- op: COUNT
breakdowns:
- response.status_code
filters:
- op: '='
column: adhoc_check
value: true
calculated_fields:
- name: adhoc_check
expression: GT($response.status_code, 200)
orders:
- op: COUNT
order: descending
time_range: 7200
Query With Relational Fields:
value:
id: abc3419d
calculations:
- op: COUNT
breakdowns:
- name
- root.response.status_code
filters:
- op: '='
column: child.response.status_code
value: 400
orders:
- op: COUNT
order: descending
time_range: 3600
compare_time_offset_seconds: 86400
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
$ref: '#/components/responses/RateLimited'
/1/queries/{datasetSlug}/{queryId}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
- name: queryId
description: The unique identifier (ID) of a query.
in: path
required: true
schema:
type: string
get:
security:
- configuration_key: []
summary: Get a Query
description: 'Retrieve a query by its ID.
'
tags:
- Queries
operationId: getQuery
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
example:
id: abc3419d
breakdowns:
- user_agent
calculations:
- op: COUNT
orders:
- op: COUNT
order: descending
limit: 10
time_range: 7200
end_time: 1676467828
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/1/query_annotations/{datasetSlug}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
post:
security:
- configuration_key: []
summary: Create a Query Annotation
description: 'Create a Query Annotation for the specified query ID.
'
tags:
- Query Annotations
operationId: createQueryAnnotation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryAnnotation'
required: true
responses:
'201':
description: Created
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/QueryAnnotation'
'400':
description: Bad Request
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-query-id:
description: The query ID is invalid.
value:
error: Query ID included in body is invalid
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/GenericError'
get:
security:
- configuration_key: []
summary: List Query Annotations
description: 'List all Query Annotations in the specified dataset.
'
tags:
- Query Annotations
operationId: listQueryAnnotations
parameters:
- name: include_board_annotations
in: query
description: 'Whether to include Query Annotations that were created from boards. By default, only Query Annotations created directly from queries are returned.
'
schema:
type: boolean
default: false
required: false
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/QueryAnnotation'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/GenericError'
/1/query_annotations/{datasetSlug}/{queryAnnotationId}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
- name: queryAnnotationId
description: The unique identifier (ID) of the annotation.
in: path
required: true
schema:
type: string
get:
security:
- configuration_key: []
summary: Get a Query Annotation
description: 'Get a Query Annotation by its ID.
'
tags:
- Query Annotations
operationId: getQueryAnnotation
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/QueryAnnotation'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/GenericError'
put:
security:
- configuration_key: []
summary: Update a Query Annotation
description: 'Update a Query Annotation by specifying its ID. The Query ID associated with the Query Annotation cannot be updated. Partial updates are not supported.
'
tags:
- Query Annotations
operationId: updateQueryAnnotation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryAnnotation'
example:
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'
required: true
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/QueryAnnotation'
example:
name: My Updated Annotation
description: A nice description of My Update Annotation
query_id: mabAMpSPDjH
'400':
description: Bad Request
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
update-includes-bad-id:
description: The ID in the URL and the ID in the request body do not match.
value:
error: Query annotation id included in body does not match URL
invalid-query-id:
description: The query ID is invalid.
value:
error: Query id included in body is invalid
cannot-update-query-id:
description: The query ID cannot be updated.
value:
error: queries in annotations cannot be changed
query-not-in-dataset:
description: The query ID does not exist in the specified dataset.
value:
error: Query is not in the dataset
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/GenericError'
delete:
security:
- configuration_key: []
summary: Delete a Query Annotation
description: 'Delete a Query Annotation by specifying its ID.
'
tags:
- Query Annotations
operationId: deleteQueryAnnotation
responses:
'204':
description: Success - no content
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/GenericError'
/1/query_results/{datasetSlug}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
post:
security:
- configuration_key: []
summary: Create a Query Result
description: '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.
A maximum duration of 7 days of data can be queried. Any queries with a `start_time`, `end_time`, or `time_range` resulting in a duration longer than 7 days will result in a `400` error response.
'
tags:
- Query Data
operationId: createQueryResult
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateQueryResultRequest'
required: true
responses:
'201':
description: Created
headers:
Location:
schema:
type: string
description: The Location header will contain the URL where the results can be fetched.
example: https://api.honeycomb.io/1/query_results/test-via-curl/HprJhV1fYyr
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResult'
examples:
Simple Query:
value:
query:
calculations:
- op: COUNT
orders:
- op: COUNT
order: descending
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
Query with Filter and Group By:
value:
query:
calculations:
- op: COUNT
breakdowns:
- user_agent
filters:
- op: '>='
column: response.status_code
value: 400
orders:
- op: COUNT
order: descending
limit: 10000
time_range: 7200
complete: false
id: hij678a
links:
query_url: https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a
graph_image_url: https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a/snapshot
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
description: Rate Limit Exceeded
content:
application/problem+json:
schema:
$ref: '#/components/schemas/DetailedError'
example:
status: 429
type: https://api.honeycomb.io/problems/rate-limited
title: You have exceeded your rate limit.
error: You have exceeded your rate limit.
detail: This endpoint allows 10 requests per minute.
default:
$ref: '#/components/responses/GenericError'
/1/query_results/{datasetSlug}/{queryResultId}:
parameters:
- $ref: '#/components/parameters/datasetSlugOrAll'
- name: queryResultId
description: The unique identifier (ID) of the query result.
in: path
required: true
schema:
type: string
get:
security:
- configuration_key: []
summary: Get Query Result
description: '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>.
'
tags:
- Query Data
operationId: getQueryResult
responses:
'200':
description: Success
headers:
Last-Modified:
schema:
type: string
description: The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified.
example: Mon, 02 Jan 2006 15:04:05 GMT
Cache-Control:
schema:
type: string
description: The max-age=N response directive indicates that the response remains fresh until N seconds after the response is generated.
example: private, max-age=86400
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResultDetails'
examples:
Simple Query:
value:
query:
calculations:
- op: COUNT
orders:
- op: COUNT
order: descending
limit: 10000
time_range: 7200
complete: true
id: dfg456
data:
series: []
results:
- data:
COUNT: 20769
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
Query with Filter and Group By:
value:
query:
calculations:
- op: COUNT
breakdowns:
- user_agent
filters:
- op: '>='
column: response.status_code
value: 400
orders:
- op: COUNT
order: descending
limit: 10000
time_range: 7200
complete: false
id: hij678a
data:
series: []
results:
- data:
COUNT: 2728
user_agent: Mozilla/5.0 (X11; Linux x86_64)
- data:
COUNT: 4
user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
- data:
COUNT: 7
user_agent: Mozilla/5.0 (Linux; Android 7.1.2; AFTMM Build/NS6265; wv)
links:
query_url: https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a
graph_image_url: https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/hij678a/snapshot
'404':
$ref: '#/components/responses/NotFound'
default:
$ref: '#/components/responses/GenericError'
components:
headers:
RateLimitPolicy:
description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"X;w=Y\".\nWhere:\n - X is the maximum number of requests allowed in a window\n\
\ - Y is the size of the window in seconds\n"
schema:
type: string
example: 100;w=60
RetryAfter:
description: 'The RFC7231 header used to indicate when a client should retry requests.
'
schema:
type: string
example: Fri, 22 Mar 2024 18:37:53 GMT
RateLimit:
description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"limit=X, remaining=Y, reset=Z\".\nWhere:\n - X is the maximum number of requests\
\ allowed in the window\n - Y is the number of requests remaining in the window\n - Z is the number of seconds until the limit resets\n"
schema:
type: string
example: limit=100, remaining=50, reset=60
parameters:
datasetSlugOrAll:
name: datasetSlug
description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.
'
in: path
required: true
schema:
type: string
schemas:
Query:
type: object
properties:
id:
type: string
readOnly: true
breakdowns:
type: array
default:
- user_agent
maxItems: 100
items:
type: string
description: the columns by which to break events down into groups
calculations:
type: array
description: the calculations to return as a time series and summary table
maxItems: 100
items:
type: object
required:
- op
properties:
op:
allOf:
- $ref: '#/components/schemas/QueryOp'
- default: COUNT
column:
type:
- 'null'
- string
description: The name of the column
name:
type:
- 'null'
- string
description: The name of the calculation. This is required if using calculation filters. Only available in Metrics Beta.
filters:
type: array
maxItems: 100
items:
type: object
required:
- column
- op
properties:
op:
$ref: '#/components/schemas/FilterOp'
column:
$ref: '#/components/schemas/FilterColumn'
value:
$ref: '#/components/schemas/FilterValue'
description: The filters with which to restrict the results of this particular calculation. Does not support relational fields. Only available in Metrics Beta.
filter_combination:
$ref: '#/components/schemas/FilterCombination'
filters:
type: array
maxItems: 100
items:
type: object
required:
- column
- op
properties:
op:
$ref: '#/components/schemas/FilterOp'
column:
$ref: '#/components/schemas/FilterColumn'
value:
$ref: '#/components/schemas/FilterValue'
description: The filters with which to restrict the considered events
filter_combination:
$ref: '#/components/schemas/FilterCombination'
formulas:
type: array
description: Mathematical formulas to be returned as a time series and summary table. Formulas operate on the results of calculations and are returned in query results instead of calculations.
Only available in Metrics Beta.
maxItems: 100
items:
type: object
required:
- name
- expression
properties:
name:
type:
- string
description: The name of the formula
expression:
type:
- string
description: An expression that follows the same syntax as calculated field expressions, but uses the names of items in the calculations list in place of column names.
granularity:
type: integer
minimum: 1
description: 'The time resolution of the query''s graph, in seconds. Given a query time range T, valid values (T/1000...T/1). If left blank, granularity may be set to a sub-second value for queries
with short time ranges.
'
orders:
type: array
maxItems: 100
items:
type: object
properties:
column:
type: string
op:
$ref: '#/components/schemas/QueryOp'
order:
type: string
default: ascending
enum:
- ascending
- descending
description: 'The terms on which to order the query results. Each term must appear in the `breakdowns` field, the `calculations` field, or the `formulas` field. Formulas and calculations with
name properties can be referenced by putting the name in the column property.
'
limit:
type: integer
default: 100
minimum: 1
maximum: 10000
description: '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 fro
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/openapi/honeycomb-queries-api-openapi.yml