logo

Queries

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.

This API allows you to create and get query objects.

Authorization

The API key must have the Manage Queries and Columns permission. Learn more about API keys here.

Create a Query

Create a query from a specification. DOES NOT run the query to retrieve results.

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
breakdowns
Array of strings <= 100 items
Default: ["user_agent"]

the columns by which to break events down into groups

Array of objects <= 100 items

the calculations to return as a time series and summary table

Array of objects <= 100 items

the filters with which to restrict the considered events

filter_combination
string
Default: "AND"

set to "OR" to match ANY filter in the filter list

Enum: "AND" "OR"
granularity
integer >= 1

The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/10).

Array of objects <= 100 items

The terms on which to order the query results. Each term must appear in either the breakdowns field or the calculations field.

limit
integer [ 1 .. 10000 ]
Default: 100

The maximum number of unique groups returned in 'results'. Aggregating many unique groups across a large time range is computationally expensive, and too high a limit with too many unique groups may cause queries to fail completey. Limiting the results to only the needed values can significantly speed up queries. The normal allowed maximum value when creating a query is 1_000. When running 'disable_series' queries, this can be overridden to be up to 10_000, so the maximum value returned from the API when fetching a query may be up to 10_000.

start_time
integer >= 1
Default: 1676399428

Absolute start time of query, in seconds since UNIX epoch. Must be <= end_time.

end_time
integer >= 1
Default: 1676467828

Absolute end time of query, in seconds since UNIX epoch.

time_range
integer >= 1
Default: 7200

Time range of query in seconds. Can be used with either start_time (seconds after start_time), end_time (seconds before end_time), or without either (seconds before now).

Array of objects <= 100 items

The Having clause allows you to filter on the results table. This operation is distinct from the Where clause, which filters the underlying events. Order By allows you to order the results, and Having filters them.

Responses
200

Success

404

Not Found

422

Invalid Query

post/1/queries/{datasetSlug}
Request samples
application/json
{
  • "breakdowns": [
    ],
  • "calculations": [
    ],
  • "filters": [
    ],
  • "filter_combination": "AND",
  • "granularity": 1,
  • "orders": [
    ],
  • "limit": 100,
  • "start_time": 1676399428,
  • "end_time": 1676467828,
  • "time_range": 7200,
  • "havings": [
    ]
}
Response samples
application/json
{
  • "id": "abc3419d",
  • "breakdowns": [
    ],
  • "calculations": [
    ],
  • "orders": [
    ],
  • "limit": 10,
  • "time_range": 7200,
  • "end_time": 1676467828
}

Get a Query

Retrieve a query by its ID.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

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

queryId
required
string

The unique identifier (ID) of a query.

Responses
200

Success

404

Not Found

get/1/queries/{datasetSlug}/{queryId}
Request samples 
Response samples 
application/json
{
  • "id": "abc3419d",
  • "breakdowns": [
    ],
  • "calculations": [
    ],
  • "orders": [
    ],
  • "limit": 10,
  • "time_range": 7200,
  • "end_time": 1676467828
}
➔ Next to Query Annotations