openapi: 3.1.0
info:
  title: Grafana Tempo HTTP Echo Search API
  description: Grafana Tempo HTTP API for querying traces, searching with TraceQL, and retrieving trace metadata. Tempo is an open-source, high-scale distributed tracing backend.
  version: 2.0.0
  contact:
    name: Grafana Labs
    url: https://grafana.com/oss/tempo/
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: http://localhost:3200
  description: Default Tempo server
tags:
- name: Search
paths:
  /api/search:
    get:
      operationId: searchTraces
      summary: Search for traces
      description: Searches for traces matching the given parameters. Supports tag-based search and TraceQL queries.
      parameters:
      - name: q
        in: query
        description: TraceQL query string
        schema:
          type: string
      - name: tags
        in: query
        description: Tag-based search in logfmt format, e.g. "service.name=myservice error=true"
        schema:
          type: string
      - name: minDuration
        in: query
        description: Minimum trace duration, e.g. "1.5s" or "500ms"
        schema:
          type: string
      - name: maxDuration
        in: query
        description: Maximum trace duration
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of traces to return
        schema:
          type: integer
          default: 20
      - name: start
        in: query
        description: Start of time range in Unix epoch seconds
        schema:
          type: integer
      - name: end
        in: query
        description: End of time range in Unix epoch seconds
        schema:
          type: integer
      - name: spss
        in: query
        description: Spans per span set, limits spans returned per set
        schema:
          type: integer
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
      tags:
      - Search
  /api/search/tags:
    get:
      operationId: getSearchTags
      summary: Get search tag names
      description: Returns a list of tag names that can be used for search.
      parameters:
      - name: scope
        in: query
        description: Scope of tags to return (resource, span, or intrinsic)
        schema:
          type: string
          enum:
          - resource
          - span
          - intrinsic
      - name: start
        in: query
        description: Start of time range in Unix epoch seconds
        schema:
          type: integer
      - name: end
        in: query
        description: End of time range in Unix epoch seconds
        schema:
          type: integer
      responses:
        '200':
          description: A list of tag names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagNamesResponse'
      tags:
      - Search
  /api/search/tag/{tagName}/values:
    get:
      operationId: getSearchTagValues
      summary: Get values for a tag
      description: Returns a list of values for a given tag name.
      parameters:
      - name: tagName
        in: path
        required: true
        description: The tag name to lookup values for
        schema:
          type: string
      - name: q
        in: query
        description: TraceQL query to filter values by
        schema:
          type: string
      - name: start
        in: query
        description: Start of time range in Unix epoch seconds
        schema:
          type: integer
      - name: end
        in: query
        description: End of time range in Unix epoch seconds
        schema:
          type: integer
      responses:
        '200':
          description: A list of tag values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagValuesResponse'
      tags:
      - Search
  /api/v2/search/tags:
    get:
      operationId: getSearchTagsV2
      summary: Get search tag names (v2)
      description: Returns tag names with their scopes. V2 endpoint provides scope information alongside tag names.
      parameters:
      - name: scope
        in: query
        description: Scope of tags to return
        schema:
          type: string
          enum:
          - resource
          - span
          - intrinsic
      - name: start
        in: query
        schema:
          type: integer
      - name: end
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Scoped tag names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagNamesV2Response'
      tags:
      - Search
  /api/v2/search/tag/{tagName}/values:
    get:
      operationId: getSearchTagValuesV2
      summary: Get values for a tag (v2)
      description: Returns tag values with their types.
      parameters:
      - name: tagName
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: TraceQL query to filter values
        schema:
          type: string
      - name: start
        in: query
        schema:
          type: integer
      - name: end
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Tag values with types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagValuesV2Response'
      tags:
      - Search
components:
  schemas:
    TagNamesResponse:
      type: object
      properties:
        tagNames:
          type: array
          items:
            type: string
    TagNamesV2Response:
      type: object
      properties:
        scopes:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              tags:
                type: array
                items:
                  type: string
    KeyValue:
      type: object
      properties:
        key:
          type: string
        value:
          type: object
          properties:
            stringValue:
              type: string
            intValue:
              type: string
            doubleValue:
              type: number
            boolValue:
              type: boolean
    TraceSearchMetadata:
      type: object
      properties:
        traceID:
          type: string
        rootServiceName:
          type: string
        rootTraceName:
          type: string
        startTimeUnixNano:
          type: string
        durationMs:
          type: integer
        spanSets:
          type: array
          items:
            type: object
            properties:
              spans:
                type: array
                items:
                  type: object
                  properties:
                    spanID:
                      type: string
                    startTimeUnixNano:
                      type: string
                    durationNanos:
                      type: string
                    attributes:
                      type: array
                      items:
                        $ref: '#/components/schemas/KeyValue'
              matched:
                type: integer
    SearchResponse:
      type: object
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/TraceSearchMetadata'
        metrics:
          type: object
          properties:
            inspectedTraces:
              type: integer
            inspectedBytes:
              type: integer
    TagValuesV2Response:
      type: object
      properties:
        tagValues:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
    TagValuesResponse:
      type: object
      properties:
        tagValues:
          type: array
          items:
            type: string