curl --request POST \
--url https://api.honeycomb.io/1/queries/{datasetSlug} \
--header 'Content-Type: application/json' \
--header 'X-Honeycomb-Team: <api-key>' \
--data '
{
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}
'{
"id": "abc3419d",
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}Create a Query
Create a query from a specification. DOES NOT run the query to retrieve results.
curl --request POST \
--url https://api.honeycomb.io/1/queries/{datasetSlug} \
--header 'Content-Type: application/json' \
--header 'X-Honeycomb-Team: <api-key>' \
--data '
{
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}
'{
"id": "abc3419d",
"calculations": [
{
"op": "COUNT"
}
],
"orders": [
{
"op": "COUNT",
"order": "descending"
}
],
"time_range": 7200
}Authorizations
Authenticate using a Honeycomb Configuration Key.
Pass the Token in the X-Honeycomb-Team header:
X-Honeycomb-Team: 1234567890123456789012
If you created your key using the API, use data.attributes.secret; this is the same value as the Token in the UI.
To learn how to create a Configuration Key, visit Manage Environment API Keys. To learn more about authenticating requests, visit API Authentication.
Path Parameters
The dataset slug or use __all__ for endpoints that support environment-wide operations.
Body
the columns by which to break events down into groups
100the calculations to return as a time series and summary table
100Show child attributes
Show child attributes
The filters with which to restrict the considered events
100Show child attributes
Show child attributes
Set to "OR" to match ANY filter in the filter list
AND, OR Mathematical formulas to be returned as a time series and summary table. Formulas operate on the results of calculations and are returned in query results instead of calculations. Only available in Metrics Beta.
100Show child attributes
Show child attributes
The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/1). If left blank, granularity may be set to a sub-second value for queries with short time ranges.
x >= 1The terms on which to order the query results. Each term must appear in the breakdowns field, the calculations field, or the formulas field. Formulas and calculations with name properties can be referenced by putting the name in the column property.
100Show child attributes
Show child attributes
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 completely. 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.
1 <= x <= 10000Absolute start time of query, in seconds since UNIX epoch. Must be <= end_time.
x >= 1Absolute end time of query, in seconds since UNIX epoch.
x >= 1Time 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).
x >= 1The 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. Formulas and calculations with name properties can be referenced by putting the name in the column property.
100Show child attributes
Show child attributes
Computed properties that are calculated by a formula.
100Show child attributes
Show child attributes
When set, offsets the query's time range by this number of seconds into the past, allowing comparison with historical data from an earlier time period. For example, setting this to 86400 (24 hours) will compare current results against data from 24 hours ago.
Note
- The offset must be greater than or equal to the query's time range duration.
Allowed values
- same time range as query time range
1800- 30 minutes3600- 1 hour7200- 2 hours28800- 8 hours86400- 24 hours604800- 7 days2419200- 28 days15724800- 6 months
1800, 3600, 7200, 28800, 86400, 604800, 2419200, 15724800 If true, query results will return aggregates without correcting for sample rates. This is useful for understanding the actual volume of data stored rather than the estimated original event counts. By default, aggregates are adjusted to reflect the estimated original event volume based on sample rates. Note: This field is not supported for triggers.
If true, the query's time range applies to the end time of each span (its start time plus its duration) instead of its start time. By default, the time range applies to span start times.
Response
Success
the columns by which to break events down into groups
100the calculations to return as a time series and summary table
100Show child attributes
Show child attributes
The filters with which to restrict the considered events
100Show child attributes
Show child attributes
Set to "OR" to match ANY filter in the filter list
AND, OR Mathematical formulas to be returned as a time series and summary table. Formulas operate on the results of calculations and are returned in query results instead of calculations. Only available in Metrics Beta.
100Show child attributes
Show child attributes
The time resolution of the query's graph, in seconds. Given a query time range T, valid values (T/1000...T/1). If left blank, granularity may be set to a sub-second value for queries with short time ranges.
x >= 1The terms on which to order the query results. Each term must appear in the breakdowns field, the calculations field, or the formulas field. Formulas and calculations with name properties can be referenced by putting the name in the column property.
100Show child attributes
Show child attributes
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 completely. 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.
1 <= x <= 10000Absolute start time of query, in seconds since UNIX epoch. Must be <= end_time.
x >= 1Absolute end time of query, in seconds since UNIX epoch.
x >= 1Time 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).
x >= 1The 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. Formulas and calculations with name properties can be referenced by putting the name in the column property.
100Show child attributes
Show child attributes
Computed properties that are calculated by a formula.
100Show child attributes
Show child attributes
When set, offsets the query's time range by this number of seconds into the past, allowing comparison with historical data from an earlier time period. For example, setting this to 86400 (24 hours) will compare current results against data from 24 hours ago.
Note
- The offset must be greater than or equal to the query's time range duration.
Allowed values
- same time range as query time range
1800- 30 minutes3600- 1 hour7200- 2 hours28800- 8 hours86400- 24 hours604800- 7 days2419200- 28 days15724800- 6 months
1800, 3600, 7200, 28800, 86400, 604800, 2419200, 15724800 If true, query results will return aggregates without correcting for sample rates. This is useful for understanding the actual volume of data stored rather than the estimated original event counts. By default, aggregates are adjusted to reflect the estimated original event volume based on sample rates. Note: This field is not supported for triggers.
If true, the query's time range applies to the end time of each span (its start time plus its duration) instead of its start time. By default, the time range applies to span start times.