honeycomb Query Data API

openapi: 3.1.0
info:
  title: Honeycomb Auth Query Data API
  description: The Honeycomb API is a REST API that provides programmatic access to the Honeycomb observability platform. It enables developers to manage datasets and columns, configure SLOs and burn alerts, set up triggers and recipients, manage boards and markers, administer environments, API keys, and access auth, query annotations, calculated fields, marker settings, reporting, dataset definitions, and service maps.
  version: '1.0'
  contact:
    name: Honeycomb Support
    url: https://support.honeycomb.io
  termsOfService: https://www.honeycomb.io/terms-of-service
servers:
- url: https://api.honeycomb.io
  description: Honeycomb Production API
security:
- ApiKeyAuth: []
tags:
- name: Query Data
  description: Access completed query result data.
paths:
  /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:
  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
    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
  parameters:
    datasetSlug:
      name: datasetSlug
      in: path
      required: true
      description: The slug identifier for the dataset.
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: Honeycomb Configuration API key. Must have appropriate permissions for the endpoint being called.
externalDocs:
  description: Honeycomb API Documentation
  url: https://api-docs.honeycomb.io/api