Query Data API

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.

Headers

The X-Honeycomb-Team header, which is your API key, is required. This API key must have the “Manage Queries and Columns” and “Run Queries” permissions enabled. Learn more about API Keys.

Please send a reasonable User-Agent header indicating as much as possible about your client. If modifying the User-Agent field is not possible, please add content to a X-Honeycomb-UserAgent header instead.

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.

Create Query Result

A Query Result can be created by sending a POST request to /1/query_results/<dataset>.

The <dataset> specified in the URL must be the same as what was used to create the Query. For environment queries, use the special __all__ token just like when you created the query.

It will run the query 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.

Create Request Body

The request body must contain the ID of a query returned from the Queries endpoint.

{
  "query_id": "<query id>"
}

Create Example Request

curl https://api.honeycomb.io/1/query_results/test-via-curl -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{"query_id":"a1b2c3d4"}'

Create Example Response

The response body will be a JSON object containing an id that is used to fetch query results from. The Location header will contain the URL where the results can be fetched (see below).

Create Example Response: Success

201 Created
Location: https://api.honeycomb.io/1/query_results/test-via-curl/HprJhV1fYyr
{
    "id": "HprJhV1fYyr"
    "complete": false
}

Create Example Response: Error query does not exist

400 Bad Request
{
    "error": "query a1b2c3d4 does not exist"
}

Create Example Response: Error Query Too Far in Past

400 Bad Request
{
    "error": "query has been rejected because the start_time/time_range is too far in the past"
}

Get Query Result

A Query Result can be retrieved by sending a GET request to /1/query_results/<dataset>/<query-result-id>.

Environment queries should use __all__ as the <dataset>, just like when they were created.

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

Get Example Request

curl https://api.honeycomb.io/1/query_results/test-via-curl/HprJhV1fYyr -X GET  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get Example Response

The response body will be a JSON object with "complete": true and the results populated once the query is complete. The response body will contain caching headers to indicate that once complete, and the Query Result may be cached, as it will not change.

Get Example Response: Incomplete Results Response Example

200 OK
{
    "id": "HprJhV1fYyr",
    "complete": false
}

Get Example Response: Success

200 OK
Last-Modified: Mon, 02 Jan 2006 15:04:05 GMT
Cache-Control: private, max-age=86400
{
    "id": "HprJhV1fYyr",
    "complete": true,
    "data": {
        "series": [
            {
                "time": "2021-04-09T14:16:00Z",
                "data": {
                    "COUNT": 1,
                    "P99(duration_ms)": 210,
                    "name": "TestGoogleCallbackLogin",
                    "test.classname": "github.com/honeycombio/hound/cmd/poodle/handlers",
                    "test.status": "passed"
                }
            },
            ... remaining series omitted for brevity ...
        ],
        "results": [
            {
                "data": {
                    "COUNT": 77481,
                    "P99(duration_ms)": 857.0309715273646,
                    "name": "TestGoogleCallbackLogin",
                    "test.classname": "github.com/honeycombio/hound/cmd/poodle/handlers",
                    "test.status": "passed"
                }
            }
        ]
    },
    "links": {
        "query_url": "https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/HprJhV1fYy",
        "graph_image_url": "https://ui.honeycomb.io/myteam/datasets/test-via-curl/result/HprJhV1fYy/snapshot"
    }
}

Get Example Response: Error Result ID does not exist

404 Not Found
{
    "error": "query not found"
}

Did you find what you were looking for?

Additional Feedback (Optional)

If you have questions, join our Pollinators Community Slack, or for Pro/Enterprise users, contact Support at support.honeycomb.io, or email at support@honeycomb.io.

Honeycomb.io Documentation

Query Data API [Ent]