Query Data API | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

Query Data API Beta

This feature is available as part of the Honeycomb Enterprise plan.

Running a new query against a Honeycomb dataset is a three-step process:

  1. Create the Query (or Query Spec), which validates that the query parameters are valid for the given dataset. Creating a query does not actually run the query to get results.
  2. Run the query asynchronously by creating a Query Result referencing the Query’s ID. This returns a Query Result ID.
  3. 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 Team API key, is required. This Team 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 3 seconds to run.

Create Query Result  🔗

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

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

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"
                }
            }
        ]
    }
}

Get Example Response: Error Result ID does not exist  🔗

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