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.
The API key must have the Manage Queries and Columns and Run Queries permission. Learn more about API keys here.
Create a Query Result
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.
Only the last 7 days of data can be queried. Any queries with a start_time, end_time, or time_range older than last 7 days will result in a 400 error response.
path Parameters
Request Body schema: application/jsonrequired
| query_id required | string The ID of a query returned from the Queries endpoint. |
| disable_series | boolean If true, will disable calculation and return of the full time-series data, usually included in the 'series' response field, instead only returning the summarized 'results'. |
| limit | integer <= 10000 If 'disable_series' is true, then a limit may optionally be given, which will override the limit normally associated with the query. Unlike normal query results which are limited to 1_000 results, 'disable_series' results may have a limit of up to 10_000. If 'disable_series' is false, then this field will be ignored. |
Created
The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.
Forbidden
Not Found
Validation Failed
Error
- Payload
- curl
{- "query_id": "mabAMpSPDjH",
- "disable_series": true,
- "limit": 10000
}- 201
- 400
- 403
- 404
- 422
- default
{- "query": {
- "calculations": [
- {
- "op": "COUNT"
}
], - "orders": [
- {
- "op": "COUNT",
- "order": "descending"
}
], - "limit": 10000,
- "time_range": 7200
}, - "complete": false,
- "id": "dfg456",
- "links": {
}
}Get Query Result
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>.
Success
Not Found
Error
- curl
- 200
- 404
- default
{- "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": {
}
}