Skip to main content
POST
/
1
/
queries
/
{datasetSlug}
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

​
X-Honeycomb-Team
string
header
required

A Honeycomb Configuration Key is required to use this API. A Configuration Key can be found in the API Keys section of the environment configuration, which can be found under Environment Settings -> API Keys -> Configuration tab. Check out our documentation to find your API Keys.

More information can be found in Manage Environments.

Path Parameters

​
datasetSlug
string
required

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

Body

application/json
​
breakdowns
string[]

the columns by which to break events down into groups

Maximum array length: 100
​
calculations
object[]

the calculations to return as a time series and summary table

Maximum array length: 100
​
filters
object[]

the filters with which to restrict the considered events

Maximum array length: 100
​
filter_combination
enum<string>
default:AND

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

Available options:
AND,
OR
​
granularity
integer

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.

Required range: x >= 1
​
orders
object[]

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

Maximum array length: 100
​
limit
integer
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 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.

Required range: 1 <= x <= 10000
​
start_time
integer
default:1676399428

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

Required range: x >= 1
​
end_time
integer
default:1676467828

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

Required range: x >= 1
​
time_range
integer
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).

Required range: x >= 1
​
havings
object[]

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.

Maximum array length: 100
​
calculated_fields
object[]

Computed properties that are calculated by a formula.

Maximum array length: 100
​
compare_time_offset_seconds
enum<integer>

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 minutes
  • 3600 - 1 hour
  • 7200 - 2 hours
  • 28800 - 8 hours
  • 86400 - 24 hours
  • 604800 - 7 days
  • 2419200 - 28 days
  • 15724800 - 6 months
Available options:
1800,
3600,
7200,
28800,
86400,
604800,
2419200,
15724800

Response

Success

​
id
string
​
breakdowns
string[]

the columns by which to break events down into groups

Maximum array length: 100
​
calculations
object[]

the calculations to return as a time series and summary table

Maximum array length: 100
​
filters
object[]

the filters with which to restrict the considered events

Maximum array length: 100
​
filter_combination
enum<string>
default:AND

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

Available options:
AND,
OR
​
granularity
integer

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.

Required range: x >= 1
​
orders
object[]

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

Maximum array length: 100
​
limit
integer
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 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.

Required range: 1 <= x <= 10000
​
start_time
integer
default:1676399428

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

Required range: x >= 1
​
end_time
integer
default:1676467828

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

Required range: x >= 1
​
time_range
integer
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).

Required range: x >= 1
​
havings
object[]

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.

Maximum array length: 100
​
calculated_fields
object[]

Computed properties that are calculated by a formula.

Maximum array length: 100
​
compare_time_offset_seconds
enum<integer>

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 minutes
  • 3600 - 1 hour
  • 7200 - 2 hours
  • 28800 - 8 hours
  • 86400 - 24 hours
  • 604800 - 7 days
  • 2419200 - 28 days
  • 15724800 - 6 months
Available options:
1800,
3600,
7200,
28800,
86400,
604800,
2419200,
15724800