Honeycomb Queries API

openapi: 3.1.0
info:
  title: Honeycomb Queries API
  description: >-
    The Honeycomb Queries API allows developers to programmatically create
    and manage query specifications within Honeycomb. Queries are used to
    identify and reference queries across other parts of the API, including
    boards, triggers, and query annotations. Developers can run queries
    asynchronously by creating a Query Result that references a Query ID,
    then polling the query result endpoint until the data is ready. The
    Query Data API complements this by providing access to query results.
  version: '1.0'
  contact:
    name: Honeycomb Support
    url: https://support.honeycomb.io
  termsOfService: https://www.honeycomb.io/terms-of-service
externalDocs:
  description: Honeycomb Queries API Documentation
  url: https://api-docs.honeycomb.io/api/queries
servers:
  - url: https://api.honeycomb.io
    description: Honeycomb Production API
tags:
  - name: Queries
    description: >-
      Create and retrieve query specifications that define what data to
      retrieve and how to aggregate it.
  - name: Query Data
    description: >-
      Access completed query result data.
  - name: Query Results
    description: >-
      Create and poll for asynchronous query results.
security:
  - ApiKeyAuth: []
paths:
  /1/queries/{datasetSlug}:
    post:
      operationId: createQuery
      summary: Create a query
      description: >-
        Creates a query specification that validates the query parameters are
        valid and returns a query ID that can be used to create query results,
        reference in boards, triggers, and query annotations.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/datasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuerySpec'
      responses:
        '201':
          description: Query created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '400':
          description: Bad request - invalid query parameters
        '401':
          description: Unauthorized
        '404':
          description: Dataset not found
  /1/queries/{datasetSlug}/{queryId}:
    get:
      operationId: getQuery
      summary: Get a query
      description: >-
        Returns a single query specification by its ID.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/datasetSlug'
        - $ref: '#/components/parameters/queryId'
      responses:
        '200':
          description: Query details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Query'
        '401':
          description: Unauthorized
        '404':
          description: Query not found
  /1/query_results/{datasetSlug}:
    post:
      operationId: createQueryResult
      summary: Create a query result
      description: >-
        Creates an asynchronous query result by referencing a Query ID. After
        creation, poll the query result endpoint until the data is complete.
      tags:
        - Query Results
      parameters:
        - $ref: '#/components/parameters/datasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query_id
              properties:
                query_id:
                  type: string
                  description: >-
                    The ID of the query specification to execute.
                disable_series:
                  type: boolean
                  description: >-
                    If true, omits the time series data from the result.
                limit:
                  type: integer
                  description: >-
                    The maximum number of result rows to return.
      responses:
        '201':
          description: Query result created and processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Dataset or query not found
  /1/query_results/{datasetSlug}/{queryResultId}:
    get:
      operationId: getQueryResult
      summary: Get a query result
      description: >-
        Returns the status and data of an asynchronous query result. Poll this
        endpoint until the complete flag is true to get the final results.
      tags:
        - Query Results
      parameters:
        - $ref: '#/components/parameters/datasetSlug'
        - $ref: '#/components/parameters/queryResultId'
      responses:
        '200':
          description: Query result status and data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '401':
          description: Unauthorized
        '404':
          description: Query result not found
  /1/query_data/{datasetSlug}:
    post:
      operationId: createQueryData
      summary: Run a query and get data
      description: >-
        Submits a query specification and returns the result data directly.
        This is a convenience endpoint that combines query creation and result
        retrieval.
      tags:
        - Query Data
      parameters:
        - $ref: '#/components/parameters/datasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuerySpec'
      responses:
        '200':
          description: Query data results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryData'
        '400':
          description: Bad request - invalid query
        '401':
          description: Unauthorized
        '404':
          description: Dataset not found
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: >-
        Honeycomb Configuration API key with Manage Queries and Columns
        permission.
  parameters:
    datasetSlug:
      name: datasetSlug
      in: path
      required: true
      description: >-
        The slug identifier for the dataset.
      schema:
        type: string
    queryId:
      name: queryId
      in: path
      required: true
      description: >-
        The unique identifier for the query.
      schema:
        type: string
    queryResultId:
      name: queryResultId
      in: path
      required: true
      description: >-
        The unique identifier for the query result.
      schema:
        type: string
  schemas:
    QuerySpec:
      type: object
      description: >-
        A query specification defining what data to retrieve and how to
        aggregate it.
      properties:
        calculations:
          type: array
          description: >-
            The calculations (aggregations) to perform.
          items:
            type: object
            properties:
              op:
                type: string
                description: >-
                  The aggregation operation.
                enum:
                  - COUNT
                  - SUM
                  - AVG
                  - COUNT_DISTINCT
                  - MAX
                  - MIN
                  - P001
                  - P01
                  - P05
                  - P10
                  - P25
                  - P50
                  - P75
                  - P90
                  - P95
                  - P99
                  - P999
                  - HEATMAP
                  - RATE_AVG
                  - RATE_SUM
                  - RATE_MAX
              column:
                type: string
                description: >-
                  The column to aggregate on.
        filters:
          type: array
          description: >-
            Filters to apply before aggregation.
          items:
            type: object
            properties:
              column:
                type: string
                description: >-
                  The column to filter on.
              op:
                type: string
                description: >-
                  The filter comparison operator.
                enum:
                  - '='
                  - '!='
                  - '>'
                  - '>='
                  - '<'
                  - '<='
                  - starts-with
                  - does-not-start-with
                  - contains
                  - does-not-contain
                  - exists
                  - does-not-exist
                  - in
                  - not-in
              value:
                description: >-
                  The value to compare against.
        filter_combination:
          type: string
          description: >-
            How to combine filters.
          enum:
            - AND
            - OR
        breakdowns:
          type: array
          description: >-
            Columns to group results by.
          items:
            type: string
        orders:
          type: array
          description: >-
            Ordering rules for the results.
          items:
            type: object
            properties:
              column:
                type: string
              op:
                type: string
              order:
                type: string
                enum:
                  - ascending
                  - descending
        time_range:
          type: integer
          description: >-
            The relative time range in seconds to query over.
        start_time:
          type: integer
          description: >-
            Unix timestamp for the query start time.
        end_time:
          type: integer
          description: >-
            Unix timestamp for the query end time.
        granularity:
          type: integer
          description: >-
            The time granularity of results in seconds.
        limit:
          type: integer
          description: >-
            Maximum number of results to return.
        havings:
          type: array
          description: >-
            Post-aggregation filters.
          items:
            type: object
            properties:
              calculate_op:
                type: string
              column:
                type: string
              op:
                type: string
              value:
                type: number
    Query:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the query.
        calculations:
          type: array
          items:
            type: object
            properties:
              op:
                type: string
              column:
                type: string
        filters:
          type: array
          items:
            type: object
            properties:
              column:
                type: string
              op:
                type: string
              value: {}
        breakdowns:
          type: array
          items:
            type: string
        orders:
          type: array
          items:
            type: object
        time_range:
          type: integer
        granularity:
          type: integer
        limit:
          type: integer
        created_at:
          type: string
          format: date-time
          description: >-
            ISO8601 formatted time the query was created.
    QueryResult:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the query result.
        query_id:
          type: string
          description: >-
            The ID of the query specification that was executed.
        complete:
          type: boolean
          description: >-
            Whether the query has finished processing.
        data:
          type: object
          description: >-
            The result data, populated when complete is true.
          properties:
            results:
              type: array
              description: >-
                The aggregated result rows.
              items:
                type: object
                additionalProperties: true
            series:
              type: array
              description: >-
                Time series data points.
              items:
                type: object
                additionalProperties: true
        links:
          type: object
          description: >-
            Links related to the query result.
          properties:
            query_url:
              type: string
              format: uri
              description: >-
                URL to view the query in the Honeycomb UI.
            graph_image_url:
              type: string
              format: uri
              description: >-
                URL to a rendered graph image of the query result.
    QueryData:
      type: object
      properties:
        results:
          type: array
          description: >-
            The aggregated result rows.
          items:
            type: object
            additionalProperties: true
        series:
          type: array
          description: >-
            Time series data points.
          items:
            type: object
            additionalProperties: true