# Create a Query

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


Endpoint: POST /1/queries/{datasetSlug}
Version: 1.0.0
Security: configuration_key

## Path parameters:

  - `datasetSlug` (string, required)
    The dataset slug or use  for endpoints that support environment-wide operations.

## Request fields (application/json):

  - `breakdowns` (array)
    the columns by which to break events down into groups

  - `calculations` (array)
    the calculations to return as a time series and summary table

  - `calculations.op` (string, required)
    Enum: "COUNT", "CONCURRENCY", "SUM", "AVG", "COUNT_DISTINCT", "HEATMAP", "MAX", "MIN", "P001", "P01", "P05", "P10", "P20", "P25", "P50", "P75", "P80", "P90", "P95", "P99", "P999", "RATE_AVG", "RATE_SUM", "RATE_MAX"

  - `calculations.column` (null,string)
    the name of the column

  - `filters` (array)
    the filters with which to restrict the considered events

  - `filters.column` (null,string)

  - `filters.value` (any)

  - `filter_combination` (string)
    set to "OR" to match ANY filter in the filter list
    Enum: "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.

  - `orders` (array)
    The terms on which to order the query results. Each term must appear in either the  field or the  field.

  - `orders.order` (string)
    Enum: "ascending", "descending"

  - `limit` (integer)
    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.

  - `start_time` (integer)
    Absolute start time of query, in seconds since UNIX epoch. Must be <= .

  - `end_time` (integer)
    Absolute end time of query, in seconds since UNIX epoch.

  - `time_range` (integer)
    Time range of query in seconds. Can be used with either  (seconds after ),  (seconds before ), or without either (seconds before now).

  - `havings` (array)
    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.

  - `havings.calculate_op` (string, required)
    Enum: "COUNT", "CONCURRENCY", "SUM", "AVG", "COUNT_DISTINCT", "MAX", "MIN", "P001", "P01", "P05", "P10", "P20", "P25", "P50", "P75", "P80", "P90", "P95", "P99", "P999", "RATE_AVG", "RATE_SUM", "RATE_MAX"

  - `havings.column` (null,string)
    The name of the column to filter against

  - `calculated_fields` (array)
    Computed properties that are calculated by a formula.

  - `calculated_fields.name` (string, required)
    The field name

  - `calculated_fields.expression` (string, required)
    The formula for your Calculated Field. To learn more about syntax and available functions, and to explore some example formulas, visit [Calculated Field Formula Reference](https://docs.honeycomb.io/reference/derived-column-formula/).

## Response 200 fields (application/json):

  - `id` (string)

  - `breakdowns` (array)
    the columns by which to break events down into groups

  - `calculations` (array)
    the calculations to return as a time series and summary table

  - `calculations.op` (string, required)
    Enum: "COUNT", "CONCURRENCY", "SUM", "AVG", "COUNT_DISTINCT", "HEATMAP", "MAX", "MIN", "P001", "P01", "P05", "P10", "P20", "P25", "P50", "P75", "P80", "P90", "P95", "P99", "P999", "RATE_AVG", "RATE_SUM", "RATE_MAX"

  - `calculations.column` (null,string)
    the name of the column

  - `filters` (array)
    the filters with which to restrict the considered events

  - `filters.column` (null,string)

  - `filters.value` (any)

  - `filter_combination` (string)
    set to "OR" to match ANY filter in the filter list
    Enum: "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.

  - `orders` (array)
    The terms on which to order the query results. Each term must appear in either the  field or the  field.

  - `orders.order` (string)
    Enum: "ascending", "descending"

  - `limit` (integer)
    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.

  - `start_time` (integer)
    Absolute start time of query, in seconds since UNIX epoch. Must be <= .

  - `end_time` (integer)
    Absolute end time of query, in seconds since UNIX epoch.

  - `time_range` (integer)
    Time range of query in seconds. Can be used with either  (seconds after ),  (seconds before ), or without either (seconds before now).

  - `havings` (array)
    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.

  - `havings.calculate_op` (string, required)
    Enum: "COUNT", "CONCURRENCY", "SUM", "AVG", "COUNT_DISTINCT", "MAX", "MIN", "P001", "P01", "P05", "P10", "P20", "P25", "P50", "P75", "P80", "P90", "P95", "P99", "P999", "RATE_AVG", "RATE_SUM", "RATE_MAX"

  - `havings.column` (null,string)
    The name of the column to filter against

  - `calculated_fields` (array)
    Computed properties that are calculated by a formula.

  - `calculated_fields.name` (string, required)
    The field name

  - `calculated_fields.expression` (string, required)
    The formula for your Calculated Field. To learn more about syntax and available functions, and to explore some example formulas, visit [Calculated Field Formula Reference](https://docs.honeycomb.io/reference/derived-column-formula/).

## Response 400 fields (application/problem+json):

  - `error` (string, required)

  - `status` (number, required)
    The HTTP status code of the error.

  - `type` (string, required)
    Type is a URI used to uniquely identify the type of error.

  - `title` (string, required)
    Title is a human-readable summary that explains the  of the problem.

  - `detail` (string)
    The general, human-readable error message.

  - `instance` (string)
    The unique identifier (ID) for this specific error.

## Response 404 fields (application/json):

  - `error` (string)

## Response 422 fields (application/problem+json):

  - `error` (string, required)

  - `status` (number, required)
    The HTTP status code of the error.

  - `type` (string, required)
    Type is a URI used to uniquely identify the type of error.

  - `title` (string, required)
    Title is a human-readable summary that explains the  of the problem.

  - `detail` (string)
    The general, human-readable error message.

  - `instance` (string)
    The unique identifier (ID) for this specific error.

  - `type_detail` (array)

  - `type_detail.field` (string)

  - `type_detail.code` (string)
    Enum: "invalid", "missing", "incorrect_type", "already_exists"

  - `type_detail.description` (string)

## Response 429 fields (application/json):

  - `error` (string)