Tempo API

openapi.yaml

openapi: 3.0.3
info:
  title: Grafana Tempo - Query Trace by ID
  version: 1.0.0
  description: >
    Minimal OpenAPI spec for Tempo's "Querying traces by id" endpoint.
    Based on Grafana Tempo API docs.
servers:
  - url: http://localhost:3200
    description: Default Tempo HTTP endpoint

paths:
  /api/traces/{traceid}:
    get:
      tags:
        - traces
      summary: Retrieve a trace by trace ID
      operationId: getTraceById
      security: []
      parameters:
        - name: traceid
          in: path
          required: true
          description: The trace ID to look up (hex string).
          schema:
            type: string
            example: 2f3e0cee77ae5dc9c17ade3689eb2e54
        - name: start
          in: query
          required: false
          description: Start of time range as Unix epoch seconds.
          schema:
            type: integer
            format: int64
            example: 1684778327
        - name: end
          in: query
          required: false
          description: End of time range as Unix epoch seconds.
          schema:
            type: integer
            format: int64
            example: 1684778927
      responses:
        "200":
          description: Trace found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TraceResponse"
              example:
                resourceSpans: []
            application/protobuf:
              schema:
                type: string
                format: binary
        "204":
          description: Trace not found in the requested time range or storage.
        "400":
          description: Bad request, such as an invalid trace ID format.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: invalid trace id
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: internal error while fetching trace

components:
  schemas:
    TraceResponse:
      type: object
      description: Placeholder for Tempo's default OpenTelemetry JSON response.
      properties:
        resourceSpans:
          type: array
          items:
            type: object
      additionalProperties: true

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
        - error