The Jaeger Query API is an HTTP/JSON API exposed by the Jaeger Query service for retrieving distributed traces, listing services and operations, querying service dependency graphs, and accessing performance metrics including latency, call rates, and error rates. A gRPC version of the Query API is also available defined in the jaeger-idl query.proto IDL.
openapi: 3.0.3
info:
title: Jaeger Query 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
paths:
/api/traces:
get:
operationId: searchTraces
summary: Search traces
description: >-
Search for traces matching the specified query parameters. Returns
a list of traces filtered by service, operation, tags, duration,
and time range.
tags:
- Traces
parameters:
- name: service
in: query
description: The service name to filter traces by.
required: true
schema:
type: string
- name: operation
in: query
description: The operation name to filter traces by.
schema:
type: string
- name: tags
in: query
description: >-
Tags to filter by in JSON format, e.g. {"http.status_code":"200"}.
schema:
type: string
- name: start
in: query
description: Start time as Unix microseconds.
schema:
type: integer
format: int64
- name: end
in: query
description: End time as Unix microseconds.
schema:
type: integer
format: int64
- name: minDuration
in: query
description: >-
Minimum trace duration filter, specified as a duration string
(e.g. 1.2s, 100ms, 500us).
schema:
type: string
- name: maxDuration
in: query
description: >-
Maximum trace duration filter, specified as a duration string
(e.g. 1.2s, 100ms, 500us).
schema:
type: string
- name: limit
in: query
description: Maximum number of traces to return.
schema:
type: integer
default: 20
- name: lookback
in: query
description: >-
How far back to search for traces, specified as a duration
string (e.g. 1h, 2d). Only used if start and end are not set.
schema:
type: string
responses:
'200':
description: A list of matching traces.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Trace'
total:
type: integer
description: Total number of matching traces.
limit:
type: integer
description: Limit applied to the query.
offset:
type: integer
description: Offset applied to the query.
errors:
type: array
items:
$ref: '#/components/schemas/StructuredError'
'400':
description: Invalid query parameters.
'500':
description: Internal server error.
/api/traces/{traceID}:
get:
operationId: getTrace
summary: Get a trace by ID
description: Retrieve a single trace by its unique trace identifier.
tags:
- Traces
parameters:
- name: traceID
in: path
required: true
description: >-
The trace ID in hexadecimal format (16 or 32 hex characters).
schema:
type: string
- name: raw
in: query
description: Return raw trace data without post-processing.
schema:
type: boolean
default: false
- name: prettyPrint
in: query
description: Pretty-print the JSON response.
schema:
type: boolean
default: false
responses:
'200':
description: The requested trace.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Trace'
errors:
type: array
items:
$ref: '#/components/schemas/StructuredError'
'404':
description: Trace not found.
'500':
description: Internal server error.
/api/services:
get:
operationId: getServices
summary: Get all services
description: >-
Retrieve a list of all service names that have reported spans
to the Jaeger backend.
tags:
- Services
responses:
'200':
description: A list of service names.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: string
total:
type: integer
limit:
type: integer
offset:
type: integer
errors:
type: array
items:
$ref: '#/components/schemas/StructuredError'
'500':
description: Internal server error.
/api/services/{service}/operations:
get:
operationId: getOperations
summary: Get operations for a service
description: >-
Retrieve a list of operation names for a given service. Operations
represent the individual endpoints or functions being traced within
a service.
tags:
- Services
parameters:
- name: service
in: path
required: true
description: The service name.
schema:
type: string
- name: spanKind
in: query
description: >-
Filter operations by span kind (e.g. server, client, producer,
consumer).
schema:
type: string
responses:
'200':
description: A list of operation names.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
name:
type: string
description: The operation name.
spanKind:
type: string
description: The span kind for this operation.
total:
type: integer
limit:
type: integer
offset:
type: integer
errors:
type: array
items:
$ref: '#/components/schemas/StructuredError'
'404':
description: Service not found.
'500':
description: Internal server error.
/api/dependencies:
get:
operationId: getDependencies
summary: Get service dependency graph
description: >-
Retrieve the dependency graph showing relationships between
services based on observed traces. Returns edges representing
calls from one service to another with call counts.
tags:
- Dependencies
parameters:
- name: endTs
in: query
description: End timestamp in Unix milliseconds.
required: true
schema:
type: integer
format: int64
- name: lookback
in: query
description: >-
Duration to look back from endTs in milliseconds.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: A list of service dependency links.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DependencyLink'
errors:
type: array
items:
$ref: '#/components/schemas/StructuredError'
'400':
description: Invalid query parameters.
'500':
description: Internal server error.
/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:
Trace:
type: object
description: >-
A trace represents the complete journey of a request through a
distributed system. It consists of one or more spans forming a
directed acyclic graph.
properties:
traceID:
type: string
description: >-
Unique trace identifier in hexadecimal format (16 or 32 hex
characters).
spans:
type: array
description: The spans that make up this trace.
items:
$ref: '#/components/schemas/Span'
processes:
type: object
description: >-
Map of process IDs to process objects. Processes represent the
services that produced spans in this trace.
additionalProperties:
$ref: '#/components/schemas/Process'
warnings:
type: array
description: Warnings generated during trace retrieval.
items:
type: string
required:
- traceID
- spans
- processes
Span:
type: object
description: >-
A span represents a single unit of work within a trace. Spans have
a start time, duration, and contain metadata about the operation
being performed.
properties:
traceID:
type: string
description: The trace ID this span belongs to.
spanID:
type: string
description: Unique span identifier in hexadecimal format.
operationName:
type: string
description: The name of the operation this span represents.
references:
type: array
description: References to other spans (parent or follows-from).
items:
$ref: '#/components/schemas/SpanReference'
flags:
type: integer
description: Span flags for sampling and other options.
startTime:
type: integer
format: int64
description: Start time of the span in Unix microseconds.
duration:
type: integer
format: int64
description: Duration of the span in microseconds.
tags:
type: array
description: Key-value pairs providing additional span metadata.
items:
$ref: '#/components/schemas/KeyValue'
logs:
type: array
description: >-
Time-stamped log entries associated with this span, used to
record events during the span lifecycle.
items:
$ref: '#/components/schemas/SpanLog'
processID:
type: string
description: >-
Reference to the process that produced this span, corresponding
to a key in the trace-level processes map.
warnings:
type: array
description: Warnings generated for this span.
items:
type: string
required:
- traceID
- spanID
- operationName
- startTime
- duration
SpanReference:
type: object
description: >-
A reference from one span to another, establishing causal
relationships within a trace.
properties:
refType:
type: string
description: The type of reference.
enum:
- CHILD_OF
- FOLLOWS_FROM
traceID:
type: string
description: The trace ID of the referenced span.
spanID:
type: string
description: The span ID of the referenced span.
required:
- refType
- traceID
- spanID
SpanLog:
type: object
description: A time-stamped log entry within a span.
properties:
timestamp:
type: integer
format: int64
description: Timestamp of the log entry in Unix microseconds.
fields:
type: array
description: Key-value pairs representing the log data.
items:
$ref: '#/components/schemas/KeyValue'
required:
- timestamp
- fields
KeyValue:
type: object
description: >-
A typed key-value pair used for span tags and log fields.
properties:
key:
type: string
description: The key name.
type:
type: string
description: The value type.
enum:
- string
- bool
- int64
- float64
- binary
value:
description: The value, type depends on the type field.
required:
- key
- type
- value
Process:
type: object
description: >-
A process represents the service instance that produced spans.
properties:
serviceName:
type: string
description: The name of the service.
tags:
type: array
description: Additional metadata about the process.
items:
$ref: '#/components/schemas/KeyValue'
required:
- serviceName
DependencyLink:
type: object
description: >-
A dependency link represents an observed call relationship between
two services within the traced system.
properties:
parent:
type: string
description: The calling (upstream) service name.
child:
type: string
description: The called (downstream) service name.
callCount:
type: integer
format: int64
description: The number of calls observed between the services.
required:
- parent
- child
- callCount
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
StructuredError:
type: object
description: A structured error returned by the API.
properties:
code:
type: integer
description: Error code.
msg:
type: string
description: Error message.
traceID:
type: string
description: >-
Trace ID associated with the error, if applicable.
parameters: {}
responses: {}
tags:
- name: Traces
description: Endpoints for searching and retrieving distributed traces.
- name: Services
description: Endpoints for listing services and their operations.
- name: Dependencies
description: Endpoints for retrieving service dependency graphs.
- name: Metrics
description: >-
Endpoints for retrieving service performance metrics including
latency, call rates, and error rates.