Honeycomb Queries API

openapi: 3.1.0
info:
  title: Honeycomb Auth Queries 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: Queries
  description: Create and retrieve query specifications that define what data to retrieve and how to aggregate it.
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
components:
  parameters:
    queryId:
      name: queryId
      in: path
      required: true
      description: The unique identifier for the query.
      schema:
        type: string
    datasetSlug:
      name: datasetSlug
      in: path
      required: true
      description: The slug identifier for the dataset.
      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.
  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