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.

All endpoints operate on a dataset and use the Team API key to authenticate. All requests should be made via HTTPS to api.honeycomb.io.

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

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 Team 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
}