# Source: https://github.com/jaegertracing/jaeger-idl/blob/main/swagger/api_v3/query_service.openapi.yaml
# Generated with protoc-gen-openapi from query_service.proto.
openapi: 3.0.3
info:
title: Jaeger Query API (v3)
version: '3.0'
description: |-
Jaeger Query API v3 — the read API exposed by the Jaeger Query service on
port 16686 (HTTP) and 16685 (gRPC). Provides endpoints to look up services,
operations, trace summaries, individual traces, and inter-service
dependency graphs. This is the OpenTelemetry-aligned successor to the
legacy /api/* HTTP API.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:16686
description: Default Jaeger Query HTTP endpoint
paths:
/api/v3/dependencies:
get:
tags:
- QueryService
operationId: QueryService_GetDependencies
parameters:
- name: startTime
in: query
description: Required. The start time for the time range to search dependencies.
schema:
type: string
format: date-time
- name: endTime
in: query
description: Required. The end time for the time range to search dependencies.
schema:
type: string
format: date-time
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.DependenciesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
/api/v3/operations:
get:
tags:
- QueryService
description: GetOperations returns operation names.
operationId: QueryService_GetOperations
parameters:
- name: service
in: query
description: Required service name.
schema:
type: string
- name: spanKind
in: query
description: Optional span kind.
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.GetOperationsResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
/api/v3/services:
get:
tags:
- QueryService
description: GetServices returns service names.
operationId: QueryService_GetServices
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.GetServicesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
/api/v3/trace-summaries:
get:
tags:
- QueryService
description: |-
FindTraceSummaries searches for traces matching the given query and streams
back lightweight summary information for each matching trace. Each response
chunk may contain one or more summaries. Use this instead of FindTraces when
full span data is not required (e.g. search results page).
operationId: QueryService_FindTraceSummaries
parameters:
- name: query.serviceName
in: query
description: service_name filters spans generated by a specific service.
schema:
type: string
- name: query.operationName
in: query
description: operation_name filters spans by a specific operation / span name.
schema:
type: string
- name: query.startTimeMin
in: query
description: |-
start_time_min is the start of the time interval (inclusive) for the query.
Only traces with spans that started on or after this time will be returned.
The HTTP API uses RFC-3339ns format.
This field is required.
schema:
type: string
format: date-time
- name: query.startTimeMax
in: query
description: |-
start_time_max is the end of the time interval (exclusive) for the query.
Only traces with spans that started before this time will be returned.
The HTTP API uses RFC-3339ns format.
This field is required.
schema:
type: string
format: date-time
- name: query.durationMin
in: query
description: |-
duration_min is the minimum duration of a span in the trace.
Only traces with spans that lasted at least this long will be returned.
The HTTP API uses Golang's time format (e.g., "10s").
schema:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: Represents a a duration between -315,576,000,000s and 315,576,000,000s (around 10000 years). Precision is in nanoseconds. 1 nanosecond is represented as 0.000000001s
- name: query.durationMax
in: query
description: |-
duration_max is the maximum duration of a span in the trace.
Only traces with spans that lasted at most this long will be returned.
The HTTP API uses Golang's time format (e.g., "10s").
schema:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: Represents a a duration between -315,576,000,000s and 315,576,000,000s (around 10000 years). Precision is in nanoseconds. 1 nanosecond is represented as 0.000000001s
- name: query.searchDepth
in: query
description: |-
search_depth defines the maximum search depth. Depending on the backend storage implementation,
this may behave like an SQL `LIMIT` clause. However, some implementations might not support
precise limits, and a larger value generally results in more traces being returned.
schema:
type: integer
format: int32
- name: query.rawTraces
in: query
description: |-
If set to true, the response will exclude any enrichments to the trace, such as clock skew adjustments.
The trace will be returned exactly as stored.
This field is optional.
schema:
type: boolean
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.FindTraceSummariesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
post:
tags:
- QueryService
description: |-
FindTraceSummaries searches for traces matching the given query and streams
back lightweight summary information for each matching trace. Each response
chunk may contain one or more summaries. Use this instead of FindTraces when
full span data is not required (e.g. search results page).
operationId: QueryService_FindTraceSummaries
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.FindTraceSummariesRequest'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.FindTraceSummariesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
/api/v3/traces:
get:
tags:
- QueryService
description: |-
FindTraces searches for traces.
See GetTrace for JSON unmarshalling.
operationId: QueryService_FindTraces
parameters:
- name: query.serviceName
in: query
description: service_name filters spans generated by a specific service.
schema:
type: string
- name: query.operationName
in: query
description: operation_name filters spans by a specific operation / span name.
schema:
type: string
- name: query.startTimeMin
in: query
description: |-
start_time_min is the start of the time interval (inclusive) for the query.
Only traces with spans that started on or after this time will be returned.
The HTTP API uses RFC-3339ns format.
This field is required.
schema:
type: string
format: date-time
- name: query.startTimeMax
in: query
description: |-
start_time_max is the end of the time interval (exclusive) for the query.
Only traces with spans that started before this time will be returned.
The HTTP API uses RFC-3339ns format.
This field is required.
schema:
type: string
format: date-time
- name: query.durationMin
in: query
description: |-
duration_min is the minimum duration of a span in the trace.
Only traces with spans that lasted at least this long will be returned.
The HTTP API uses Golang's time format (e.g., "10s").
schema:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: Represents a a duration between -315,576,000,000s and 315,576,000,000s (around 10000 years). Precision is in nanoseconds. 1 nanosecond is represented as 0.000000001s
- name: query.durationMax
in: query
description: |-
duration_max is the maximum duration of a span in the trace.
Only traces with spans that lasted at most this long will be returned.
The HTTP API uses Golang's time format (e.g., "10s").
schema:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: Represents a a duration between -315,576,000,000s and 315,576,000,000s (around 10000 years). Precision is in nanoseconds. 1 nanosecond is represented as 0.000000001s
- name: query.searchDepth
in: query
description: |-
search_depth defines the maximum search depth. Depending on the backend storage implementation,
this may behave like an SQL `LIMIT` clause. However, some implementations might not support
precise limits, and a larger value generally results in more traces being returned.
schema:
type: integer
format: int32
- name: query.rawTraces
in: query
description: |-
If set to true, the response will exclude any enrichments to the trace, such as clock skew adjustments.
The trace will be returned exactly as stored.
This field is optional.
schema:
type: boolean
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/opentelemetry.proto.trace.v1.TracesData'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
post:
tags:
- QueryService
description: |-
FindTraces searches for traces.
See GetTrace for JSON unmarshalling.
operationId: QueryService_FindTracesPost
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/jaeger.api_v3.FindTracesRequest'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/opentelemetry.proto.trace.v1.TracesData'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
/api/v3/traces/{traceId}:
get:
tags:
- QueryService
description: |-
GetTrace returns a single trace.
Note that the JSON response over HTTP is wrapped into result envelope "{"result": ...}"
It means that the JSON response cannot be directly unmarshalled using JSONPb.
This can be fixed by first parsing into user-defined envelope with standard JSON library
or string manipulation to remove the envelope. Alternatively generate objects using OpenAPI.
operationId: QueryService_GetTrace
parameters:
- name: traceId
in: path
description: Hex encoded 64 or 128 bit trace ID.
required: true
schema:
type: string
- name: startTime
in: query
description: Optional. The start time to search trace ID.
schema:
type: string
format: date-time
- name: endTime
in: query
description: Optional. The end time to search trace ID.
schema:
type: string
format: date-time
- name: rawTraces
in: query
description: |-
Optional. If set to true, the response will not include any
enrichments to the trace, such as clock skew adjustment.
Instead, the trace will be returned exactly as stored.
schema:
type: boolean
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/opentelemetry.proto.trace.v1.TracesData'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
components:
schemas:
google.protobuf.Any:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
google.rpc.Status:
type: object
properties:
code:
type: integer
description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
format: int32
message:
type: string
description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/google.protobuf.Any'
description: A list of messages that carry the error details. There is a common set of message types for APIs to use.
description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
jaeger.api_v3.DependenciesResponse:
required:
- dependencies
type: object
properties:
dependencies:
type: array
items:
$ref: '#/components/schemas/jaeger.api_v3.Dependency'
jaeger.api_v3.Dependency:
required:
- parent
- child
- callCount
type: object
properties:
parent:
type: string
child:
type: string
callCount:
type: string
jaeger.api_v3.FindTraceSummariesRequest:
type: object
properties:
query:
$ref: '#/components/schemas/jaeger.api_v3.TraceQueryParameters'
description: Request object for FindTraceSummaries.
jaeger.api_v3.FindTraceSummariesResponse:
type: object
properties:
summaries:
type: array
items:
$ref: '#/components/schemas/jaeger.api_v3.TraceSummary'
description: |-
Response chunk for FindTraceSummaries. A single RPC call may yield multiple
chunks, each carrying one or more summaries, mirroring the chunked streaming
used by FindTraces / GetTrace.
jaeger.api_v3.FindTracesRequest:
type: object
properties:
query:
$ref: '#/components/schemas/jaeger.api_v3.TraceQueryParameters'
description: Request object to search traces.
jaeger.api_v3.GetOperationsResponse:
required:
- operations
type: object
properties:
operations:
type: array
items:
$ref: '#/components/schemas/jaeger.api_v3.Operation'
description: Response object to get operation names.
jaeger.api_v3.GetServicesResponse:
required:
- services
type: object
properties:
services:
type: array
items:
type: string
description: Response object to get service names.
jaeger.api_v3.Operation:
required:
- name
- spanKind
type: object
properties:
name:
type: string
spanKind:
type: string
description: Operation encapsulates information about operation.
jaeger.api_v3.ServiceSummary:
required:
- name
type: object
properties:
name:
type: string
description: Name of the service.
spanCount:
type: integer
description: Number of spans attributed to this service in the trace.
format: int32
errorSpanCount:
type: integer
description: |-
Number of spans from this service that carry OTEL StatusCode = ERROR.
The UI renders an error icon when this value is > 0.
Only spans explicitly owned by this service are counted; there is no
error propagation from child spans of other services.
format: int32
description: |-
ServiceSummary contains per-service statistics for a trace, matching
what the UI renders as a coloured tag in the search results row.
jaeger.api_v3.TraceQueryParameters:
type: object
properties:
serviceName:
type: string
description: service_name filters spans generated by a specific service.
operationName:
type: string
description: operation_name filters spans by a specific operation / span name.
attributes:
example: '{"http.status_code":"200"}'
type: string
additionalProperties:
type: string
description: |-
attributes contains key-value pairs where the key is the attribute name
and the value is its string representation. Attributes are matched against
span and resource attributes. At least one span must match all specified attributes.
The HTTP API expects this as a URL-encoded JSON string map.
Example: {"http.status_code":"200","error":"true"}
startTimeMin:
type: string
description: |-
start_time_min is the start of the time interval (inclusive) for the query.
Only traces with spans that started on or after this time will be returned.
The HTTP API uses RFC-3339ns format.
This field is required.
format: date-time
startTimeMax:
type: string
description: |-
start_time_max is the end of the time interval (exclusive) for the query.
Only traces with spans that started before this time will be returned.
The HTTP API uses RFC-3339ns format.
This field is required.
format: date-time
durationMin:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: |-
duration_min is the minimum duration of a span in the trace.
Only traces with spans that lasted at least this long will be returned.
The HTTP API uses Golang's time format (e.g., "10s").
durationMax:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: |-
duration_max is the maximum duration of a span in the trace.
Only traces with spans that lasted at most this long will be returned.
The HTTP API uses Golang's time format (e.g., "10s").
searchDepth:
type: integer
description: |-
search_depth defines the maximum search depth. Depending on the backend storage implementation,
this may behave like an SQL `LIMIT` clause. However, some implementations might not support
precise limits, and a larger value generally results in more traces being returned.
format: int32
rawTraces:
type: boolean
description: |-
If set to true, the response will exclude any enrichments to the trace, such as clock skew adjustments.
The trace will be returned exactly as stored.
This field is optional.
description: |-
Query parameters to find traces.
All fields form a conjunction (e.g., "service_name='X' AND operation_name='Y' AND ..."),
except for `search_depth` and `raw_traces`.
Fields are matched against individual spans, not the trace level. The results include
traces with at least one matching span.
The results have no guaranteed ordering.
jaeger.api_v3.TraceSummary:
required:
- traceId
type: object
properties:
traceId:
type: string
description: Hex-encoded 128-bit trace ID.
rootServiceName:
type: string
description: Name of the service that owns the root span.
rootOperationName:
type: string
description: Operation name of the root span.
minStartTimeUnixNano:
type: string
description: |-
Start timestamp of the earliest span in the trace (Unix nanoseconds).
Named to match the OTLP convention (e.g. startTimeUnixNano in OTLP span JSON).
proto3 JSON encoding: fixed64/uint64/int64 fields are serialised as decimal
strings to avoid float64 precision loss in JavaScript for values above 2^53.
maxEndTimeUnixNano:
type: string
description: |-
End timestamp of the latest span in the trace (Unix nanoseconds).
The UI may compute duration as BigInt(maxEndTimeUnixNano) - BigInt(minStartTimeUnixNano).
spanCount:
type: integer
description: Total number of spans in the trace.
format: int32
errorSpanCount:
type: integer
description: Number of spans that carry an error indicator (OTEL StatusCode = ERROR).
format: int32
orphanSpanCount:
type: integer
description: |-
Number of spans whose parent span ID is not present in this trace.
A non-zero value indicates an incomplete or partial trace.
format: int32
services:
type: array
items:
$ref: '#/components/schemas/jaeger.api_v3.ServiceSummary'
description: |-
Per-service breakdown, one entry per distinct service name observed
across all spans, sorted by name.
description: |-
TraceSummary contains lightweight summary information about a trace,
suitable for display in search result lists.
opentelemetry.proto.common.v1.AnyValue:
type: object
properties:
stringValue:
type: string
boolValue:
type: boolean
intValue:
type: string
doubleValue:
type: number
format: double
arrayValue:
$ref: '#/components/schemas/opentelemetry.proto.common.v1.ArrayValue'
kvlistValue:
$ref: '#/components/schemas/opentelemetry.proto.common.v1.KeyValueList'
bytesValue:
type: string
format: bytes
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.
opentelemetry.proto.common.v1.ArrayValue:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/opentelemetry.proto.common.v1.AnyValue'
description: Array of values. The array may be empty (contain 0 elements).
description: |-
ArrayValue is a list of AnyValue messages. We need ArrayValue as a message
since oneof in AnyValue does not allow repeated fields.
opentelemetry.proto.common.v1.InstrumentationScope:
type: object
properties:
name:
type: string
description: An empty instrumentation scope name means the name is unknown.
version:
type: string
attributes:
type: array
items:
$ref: '#/components/schemas/opentelemetry.proto.common.v1.KeyValue'
description: |-
Additional attributes that describe the scope. [Optional].
Attribute keys MUST be unique (it is not allowed to have more than one
attribute with the same key).
droppedAttributesCount:
type: integer
format: uint32
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jaeger-io/refs/heads/main/openapi/jaeger-query-api-openapi.yml