Dash0 Query SQL API

openapi: 3.2.0
info:
  title: Dash0 Edge Collectors Query SQL API
  version: 1.0.0
  description: '## Request body size limit


    Most API endpoints enforce a maximum request body size of 256KB. Bulk

    endpoints accept a larger body size per request to accommodate batched

    payloads.


    Requests exceeding the applicable limit are rejected with a

    `413 Content Too Large` response.

    '
servers:
- url: https://api.eu-west-1.aws.dash0.com
  description: API endpoint for AWS region EU (Ireland)
- url: https://api.eu-central-1.aws.dash0.com
  description: API endpoint for AWS region EU (Germany)
- url: https://api.us-west-2.aws.dash0.com
  description: API endpoint for AWS region US (Oregon)
- url: https://api.europe-west4.gcp.dash0.com
  description: API endpoint for GCP region EU (Netherlands)
tags:
- name: Query SQL
paths:
  /api/sql:
    post:
      summary: Execute a SQL query and return results as JSON.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteSqlRequest'
      responses:
        '200':
          description: Returns the SQL query results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteSqlResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Query SQL
      operationId: post_api-sql
components:
  schemas:
    ResultRows:
      type: array
      items:
        $ref: '#/components/schemas/ResultRow'
    ExecuteSqlRequest:
      properties:
        timeRange:
          $ref: '#/components/schemas/TimeReferenceRange'
        dataset:
          $ref: '#/components/schemas/Dataset'
        query:
          type: string
      required:
      - timeRange
      - query
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
        traceId:
          type: string
      required:
      - code
      - message
    ResultRow:
      properties:
        values:
          type: array
          items:
            $ref: '#/components/schemas/KeyValue'
      required:
      - values
    TimeReferenceRange:
      description: 'A range of time between two time references.

        '
      properties:
        from:
          $ref: '#/components/schemas/TimeReference'
        to:
          $ref: '#/components/schemas/TimeReference'
      required:
      - from
      - to
      example:
        from: now-30m
        to: now
    Progress:
      properties:
        rowsRead:
          type: integer
          format: uint64
        bytesRead:
          type: integer
          format: uint64
        totalRowsToRead:
          type: integer
          format: uint64
        executionTimeMillis:
          type: integer
          format: uint64
      required:
      - rowsRead
      - bytesRead
      - totalRowsToRead
      - executionTimeMillis
    FixedTime:
      type: string
      format: date-time
      description: 'A fixed point in time represented as an RFC 3339 date-time string.


        **Format**: `YYYY-MM-DDTHH:MM:SSZ` (UTC) or `YYYY-MM-DDTHH:MM:SS±HH:MM` (with timezone offset)


        **Examples**:

        - `2024-01-15T14:30:00Z`

        - `2024-01-15T14:30:00+08:00`

        '
    TimeRange:
      properties:
        from:
          $ref: '#/components/schemas/FixedTime'
        to:
          $ref: '#/components/schemas/FixedTime'
      required:
      - from
      - to
    TimeReference:
      x-go-type: any
      oneOf:
      - $ref: '#/components/schemas/FixedTime'
      - $ref: '#/components/schemas/FixedTimeUnix'
      - $ref: '#/components/schemas/RelativeTime'
    D0QLWarnings:
      type: array
      items:
        type: string
    QueryError:
      description: 'Structured error information for query errors. Present alongside the error string when the error is related to the user''s query (syntax, semantic, or execution errors). Not present for system-level errors (unauthorized access, unexpected failures).

        '
      properties:
        title:
          type: string
          description: Short error title in plain text (no markdown), e.g. Syntax error - Invalid LIMIT clause
        description:
          type: string
          description: Human-readable explanation of what went wrong and how to fix it. May contain markdown (inline code, bold, lists).
        correctedQuery:
          type: string
          description: Validated and formatted corrected SQL query. Only present when an AI-suggested correction is available and passes validation.
      required:
      - title
      - description
    AnyValue:
      description: AnyValue is used to represent any type of attribute value. AnyValue may contain a primitive value such as a string or integer or it may contain an arbitrary nested object containing arrays, key-value lists and primitives.
      type: object
      properties:
        stringValue:
          type: string
        boolValue:
          type: boolean
        intValue:
          type: string
          format: int64
        doubleValue:
          type: number
          format: double
        bytesValue:
          type: string
          format: byte
    KeyValue:
      description: KeyValue is a key-value pair that is used to store Span attributes, Link attributes, etc.
      type: object
      properties:
        key:
          type: string
        value:
          $ref: '#/components/schemas/AnyValue'
      required:
      - key
      - value
    ExecuteSqlResponse:
      properties:
        executionTime:
          $ref: '#/components/schemas/FixedTime'
        timeRange:
          $ref: '#/components/schemas/TimeRange'
        error:
          type: string
        queryError:
          $ref: '#/components/schemas/QueryError'
        progress:
          $ref: '#/components/schemas/Progress'
        resultRows:
          $ref: '#/components/schemas/ResultRows'
        warnings:
          $ref: '#/components/schemas/D0QLWarnings'
      required:
      - executionTime
      - timeRange
      - warnings
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
    FixedTimeUnix:
      description: The time corresponding to the given unix time in seconds and nanoseconds (as decimal places) since January 1, 1970 UTC.
      type: string
    RelativeTime:
      type: string
      pattern: ^now.*$
      description: 'A relative time reference based on the current time ("now").


        **Format**: `now[+/-duration]`


        **Examples**:

        - `now` - current time

        - `now-30m` - 30 minutes ago

        - `now-1h` - 1 hour ago

        - `now-1d` - 1 day ago


        **Duration Units**:

        - `s` - seconds

        - `m` - minutes

        - `h` - hours

        - `d` - days

        - `w` - weeks

        - `M` - months

        '
    Dataset:
      type: string
      pattern: ^[a-zA-Z0-9_-]{3,26}$
      description: Optional dataset to query across. Defaults to whatever is configured to be the default dataset for the organization.