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.
Securityconfiguration_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
Payload
curl
application/json
{
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}
Response samples
200
404
422
application/json
{
"id": "abc3419d",
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}
Get a Query
Retrieve a query by its ID.
Securityconfiguration_key
Request
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.