Queries 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

Queries API

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.

You can create and get query objects.

In the API, queries are also used in the Boards API, Triggers API, Query Annotations API, and Query Data API.

Fields on a Query 

See Query Specification for the detailed description of fields.

Authorization and Headers 

The only expected header is X-Honeycomb-Team, which is your API key, and it is required. The API key must have the Manage Queries and Columns permission. Learn more about API keys.

Create a Query 

Queries are created by sending a POST request to /1/queries/<DATASET_NAME>.

The body should be a JSON encoded object including a Query Specification. The ID may not be set during creation.

When a query is successfully created, the API will respond with HTTP status 200 and will return a JSON object representing that query.

Create Example Request 

An example, creating a query on the TestViaCurl dataset:

curl https://api.honeycomb.io/1/queries/test-via-curl -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '
{
  "breakdowns": ["user_agent"],
  "calculations": [{ "op": "COUNT" }],
  "orders": [{ "op": "COUNT", "order": "descending" }],
  "limit": 10,
  "time_range": 3600,
  "end_time": 1514768400
}
'

Create Example Response 

{
  "id": "abc3419d",
  "breakdowns": ["user_agent"],
  "calculations": [{ "op": "COUNT" }],
  "orders": [{ "op": "COUNT", "order": "descending" }],
  "limit": 10,
  "time_range": 3600,
  "end_time": 1514768400
}

Get a Query 

A query can be retrieved by sending a GET request to /1/queries/<dataset>/<query_id>.

Get Example Request 

As an example, this curl request will retrieve the query:

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

Get Example Response 

{
  "id": "abc3419d",
  "breakdowns": ["user_agent"],
  "calculations": [{ "op": "COUNT" }],
  "orders": [{ "op": "COUNT", "order": "descending" }],
  "limit": 10,
  "time_range": 3600,
  "end_time": 1514768400
}

Environment Queries 

Honeycomb Classic customers do not have environments and therefore cannot use environment queries.

Queries that target all the datasets within an environment can be created and read with the same APIs as above, using the special __all__ token in the URL instead of a dataset name. Both creating and reading environment queries is supported.

When run, environment queries target all the datasets existing in your environment, equivalent to selecting the “All datasets in [Your Environment]” option in the UI.

Environment Query Example Request 

curl https://api.honeycomb.io/1/queries/__all__ -X POST  \
    -H "X-Honeycomb-Team: YOUR_API_KEY"  \
    -d '{ ...json... }'

Did you find what you were looking for?