logo

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.

Authorization

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.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

The dataset slug or use __all__ for endpoints that support environment-wide operations.

Request Body schema: application/json
required
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.

Responses
201

Created

400

Bad Request

403

Forbidden

404

Not Found

422

Validation Failed

default

Error

post/1/query_results/{datasetSlug}
Request samples
application/json
{
  • "query_id": "mabAMpSPDjH",
  • "disable_series": true,
  • "limit": 10000
}
Response samples
application/json
{}

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>.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

The dataset slug or use __all__ for endpoints that support environment-wide operations.

queryResultId
required
string

The unique identifier (ID) of the query result.

Responses
200

Success

404

Not Found

default

Error

get/1/query_results/{datasetSlug}/{queryResultId}
Request samples 
Response samples 
application/json
{
  • "query": {
    },
  • "id": "sGUnkBHgRFN",
  • "complete": true,
  • "data": {
    },
  • "links": {}
}
➔ Next to Recipients