openapi: 3.0.3
info:
  title: Jaeger Query Dependencies Metrics API
  description: The Jaeger Query API provides HTTP endpoints for retrieving trace data, service information, operations, and dependency graphs from the Jaeger distributed tracing backend. This API is exposed by the jaeger-query component and is used by the Jaeger UI and other clients to search and retrieve distributed traces collected across microservices.
  version: 1.0.0
  contact:
    name: Jaeger Project
    url: https://www.jaegertracing.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:16686
  description: Default Jaeger Query server
tags:
- name: Metrics
  description: Endpoints for retrieving service performance metrics including latency, call rates, and error rates.
paths:
  /api/metrics/latencies:
    get:
      operationId: getLatencyMetrics
      summary: Get latency metrics
      description: Retrieve latency metrics (P50, P75, P95, P99) for a service, grouped by time buckets. Requires the metrics storage backend to be configured.
      tags:
      - Metrics
      parameters:
      - name: service
        in: query
        required: true
        description: The service name.
        schema:
          type: string
      - name: quantile
        in: query
        required: true
        description: The quantile to retrieve (e.g. 0.5, 0.75, 0.95, 0.99).
        schema:
          type: number
          format: double
      - name: endTs
        in: query
        description: End timestamp in Unix milliseconds.
        schema:
          type: integer
          format: int64
      - name: lookback
        in: query
        description: Duration to look back in milliseconds.
        schema:
          type: integer
          format: int64
      - name: step
        in: query
        description: Step duration for bucketing in milliseconds.
        schema:
          type: integer
          format: int64
      - name: ratePer
        in: query
        description: Rate normalization duration in milliseconds.
        schema:
          type: integer
          format: int64
      - name: spanKind
        in: query
        description: Filter by span kind.
        schema:
          type: string
      responses:
        '200':
          description: Latency metric data points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricResponse'
        '400':
          description: Invalid query parameters.
        '500':
          description: Internal server error.
  /api/metrics/calls:
    get:
      operationId: getCallMetrics
      summary: Get call rate metrics
      description: Retrieve call rate metrics for a service, grouped by time buckets. Requires the metrics storage backend to be configured.
      tags:
      - Metrics
      parameters:
      - name: service
        in: query
        required: true
        description: The service name.
        schema:
          type: string
      - name: endTs
        in: query
        description: End timestamp in Unix milliseconds.
        schema:
          type: integer
          format: int64
      - name: lookback
        in: query
        description: Duration to look back in milliseconds.
        schema:
          type: integer
          format: int64
      - name: step
        in: query
        description: Step duration for bucketing in milliseconds.
        schema:
          type: integer
          format: int64
      - name: ratePer
        in: query
        description: Rate normalization duration in milliseconds.
        schema:
          type: integer
          format: int64
      - name: spanKind
        in: query
        description: Filter by span kind.
        schema:
          type: string
      responses:
        '200':
          description: Call rate metric data points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricResponse'
        '400':
          description: Invalid query parameters.
        '500':
          description: Internal server error.
  /api/metrics/errors:
    get:
      operationId: getErrorMetrics
      summary: Get error rate metrics
      description: Retrieve error rate metrics for a service, grouped by time buckets. Requires the metrics storage backend to be configured.
      tags:
      - Metrics
      parameters:
      - name: service
        in: query
        required: true
        description: The service name.
        schema:
          type: string
      - name: endTs
        in: query
        description: End timestamp in Unix milliseconds.
        schema:
          type: integer
          format: int64
      - name: lookback
        in: query
        description: Duration to look back in milliseconds.
        schema:
          type: integer
          format: int64
      - name: step
        in: query
        description: Step duration for bucketing in milliseconds.
        schema:
          type: integer
          format: int64
      - name: ratePer
        in: query
        description: Rate normalization duration in milliseconds.
        schema:
          type: integer
          format: int64
      - name: spanKind
        in: query
        description: Filter by span kind.
        schema:
          type: string
      responses:
        '200':
          description: Error rate metric data points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricResponse'
        '400':
          description: Invalid query parameters.
        '500':
          description: Internal server error.
  /api/metrics/minstep:
    get:
      operationId: getMinStep
      summary: Get minimum step duration
      description: Retrieve the minimum time resolution (step) supported by the metrics backend.
      tags:
      - Metrics
      responses:
        '200':
          description: The minimum step duration in milliseconds.
          content:
            application/json:
              schema:
                type: integer
                format: int64
        '500':
          description: Internal server error.
components:
  schemas:
    MetricResponse:
      type: object
      description: Response containing time-series metric data.
      properties:
        name:
          type: string
          description: The name of the metric.
        type:
          type: string
          description: The type of metric (e.g. GAUGE).
        help:
          type: string
          description: Help text describing the metric.
        metrics:
          type: array
          items:
            type: object
            properties:
              labels:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    value:
                      type: string
              metricPoints:
                type: array
                items:
                  type: object
                  properties:
                    timestamp:
                      type: string
                      format: date-time
                    gaugeValue:
                      type: object
                      properties:
                        doubleValue:
                          type: number
                          format: double