API reference · v0.1.0

Traces HTTP API

Tempo-compatible trace query and OTLP/Zipkin HTTP ingestion API. OTLP and Jaeger gRPC services are documented separately. Generated from the OpenAPI 3.1 document shipped with the server.

Base URLs

Writers serve every /write route and readers serve every /read route. The operator creates a Service for each, named after the Traces resource. Any writer accepts any write and forwards it to the owning shard, so plain round-robin load balancing is enough. OTLP/gRPC is served on 4317 and Jaeger gRPC on 14250 on every writer, outside this HTTP API.

Authentication

Requests use HTTP basic auth. Each NamespaceAuthentication grants one username read or write on one namespace, with the password held in a Secret. Probes and self-metrics are unauthenticated.

Namespaces

Data is partitioned into tenant namespaces, and every data route carries one as /read/ns/{namespace} or /write/ns/{namespace}. A Tempo data source pointed at http://traces-reader.telemetry:3200/read/ns/default works unchanged.

Errors and backpressure

Errors use the Tempo error envelope with a 4xx or 5xx status. When object storage falls behind, writers reject new batches with 429 and a Retry-After header; configure your agent to retry them.

Base URLs

writer: http://traces-writer.telemetry:3200
reader: http://traces-reader.telemetry:3200

Endpoints15

GET/read/ns/…/api/traces/{trace_id}
GET/read/ns/…/api/v2/traces/{trace_id}
GET/read/ns/…/api/metrics/query_range
GET/read/ns/…/api/search
GET/read/ns/…/api/search/tag/{name}/values
GET/read/ns/…/api/search/tags
GET/read/ns/…/api/v1/tag/{name}/values
GET/read/ns/…/api/v1/tags
GET/read/ns/…/api/v2/search/tag/{name}/values
GET/read/ns/…/api/v2/search/tags
POST/write/ns/…/api/v2/spans
POST/write/ns/…/v1/traces
GET/-/healthy
GET/-/ready
GET/read/ns/…/api/echo

Error · 400

{
  "error": "invalid TraceQL query: unexpected token at 1:12"
}

Resource

traces

Trace lookup by ID. Readers merge partial traces from every shard the ID could route to.

Get trace (v1)

GET/read/ns/{namespace}/api/traces/{trace_id}

Fetches a full trace by its 32-character hex ID. Returns OTLP JSON by default; send a protobuf Accept header for protobuf.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.
trace_idstringrequired
32-character hexadecimal trace ID

Responses

200Tempo v1 trace responseapplication/jsonapplication/x-protobuf
›TraceResponse
- batchesobjectrequired
404Trace not found

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/traces/4bf92f3577b34da6a3ce929d0e0e4736 \
  -u reader:$PASSWORD

Response · 200

{
  "batches": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "checkout"
            }
          }
        ]
      },
      "scopeSpans": []
    }
  ]
}

Get trace (v2)

GET/read/ns/{namespace}/api/v2/traces/{trace_id}

Tempo v2 trace lookup. Same lookup as v1, wrapped in the v2 response envelope.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.
trace_idstringrequired
32-character hexadecimal trace ID

Responses

200Tempo v2 trace responseapplication/jsonapplication/x-protobuf
›TraceResponse
- batchesobjectrequired
404Trace not found

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/v2/traces/4bf92f3577b34da6a3ce929d0e0e4736 \
  -u reader:$PASSWORD

Response · 200

{
  "trace": {
    "batches": [
      {
        "resource": {
          "attributes": [
            {
              "key": "service.name",
              "value": {
                "stringValue": "checkout"
              }
            }
          ]
        },
        "scopeSpans": []
      }
    ]
  }
}

Resource

search

TraceQL search and tag discovery.

TraceQL metrics

GET/read/ns/{namespace}/api/metrics/query_range

Routed for Grafana compatibility. TraceQL metrics are not implemented yet, so this returns 501.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Responses

501TraceQL metrics are not implemented

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/metrics/query_range \
  -u reader:$PASSWORD

Search traces

GET/read/ns/{namespace}/api/search

Runs a TraceQL query (q) or a legacy tags selector and returns matching trace summaries.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

qstring
TraceQL expression
tagsstring
Legacy key=value selector
startinteger · int64
Unix seconds
Minimum 0
endinteger · int64
Unix seconds
Minimum 0
limitinteger
Maximum number of results to return.
Minimum 0

Responses

200Matching trace summariesapplication/json
›SearchResponse
- tracesarray of objectrequired
400Invalid TraceQL queryapplication/json
›ErrorEnvelope
- errorstringrequired

Request

curl -G http://traces-reader.telemetry:3200/read/ns/default/api/search \
  -u reader:$PASSWORD \
  --data-urlencode 'q={ resource.service.name = "checkout" && duration > 500ms }' \
  --data-urlencode 'start=1791460800' \
  --data-urlencode 'end=1791464400' \
  --data-urlencode 'limit=20'

Response · 200

{
  "traces": [
    {
      "traceID": "4bf92f3577b34da6a3ce929d0e0e4736",
      "rootServiceName": "checkout",
      "rootTraceName": "POST /pay",
      "startTimeUnixNano": "1791464400000000000",
      "durationMs": 412
    }
  ],
  "metrics": {
    "inspectedTraces": 1840
  }
}

Tag values (legacy)

GET/read/ns/{namespace}/api/search/tag/{name}/values

Legacy tag-value discovery.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.
namestringrequired
Attribute name, such as resource.service.name.

Query parameters

qstring
TraceQL query.
startinteger · int64
Start of the search window in Unix seconds.
Minimum 0
endinteger · int64
End of the search window in Unix seconds.
Minimum 0

Responses

200Tempo tag values

Request

curl -G http://traces-reader.telemetry:3200/read/ns/default/api/search/tag/resource.service.name/values \
  -u reader:$PASSWORD \
  --data-urlencode 'q={ resource.service.name = "checkout" && duration > 500ms }' \
  --data-urlencode 'start=1791460800' \
  --data-urlencode 'end=1791464400'

List tags (legacy)

GET/read/ns/{namespace}/api/search/tags

Legacy tag-name discovery.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Responses

200Tempo tag names

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/search/tags \
  -u reader:$PASSWORD

Tag values (v1)

GET/read/ns/{namespace}/api/v1/tag/{name}/values

Tempo v1 tag-value discovery.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.
namestringrequired
Attribute name, such as resource.service.name.

Responses

200Tempo v1 tag values

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/v1/tag/resource.service.name/values \
  -u reader:$PASSWORD

List tags (v1)

GET/read/ns/{namespace}/api/v1/tags

Tempo v1 tag-name discovery.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Responses

200Tempo v1 tag names

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/v1/tags \
  -u reader:$PASSWORD

Tag values (v2)

GET/read/ns/{namespace}/api/v2/search/tag/{name}/values

Typed tag values for one attribute, such as resource.service.name.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.
namestringrequired
Attribute name, such as resource.service.name.

Query parameters

scopestring
Attribute scope: resource, span, or intrinsic.
qstring
TraceQL query.
startinteger · int64
Start of the search window in Unix seconds.
Minimum 0
endinteger · int64
End of the search window in Unix seconds.
Minimum 0

Responses

200Tempo v2 tag values

Request

curl -G http://traces-reader.telemetry:3200/read/ns/default/api/v2/search/tag/resource.service.name/values \
  -u reader:$PASSWORD \
  --data-urlencode 'q={ resource.service.name = "checkout" && duration > 500ms }' \
  --data-urlencode 'start=1791460800' \
  --data-urlencode 'end=1791464400'

Response · 200

{
  "tagValues": [
    {
      "type": "string",
      "value": "checkout"
    },
    {
      "type": "string",
      "value": "ledger"
    }
  ]
}

List tags (v2)

GET/read/ns/{namespace}/api/v2/search/tags

Scoped tag-name discovery. Filter by scope (resource, span, intrinsic) and an optional TraceQL q.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

scopestring
Attribute scope: resource, span, or intrinsic.
qstring
TraceQL query.
startinteger · int64
Start of the search window in Unix seconds.
Minimum 0
endinteger · int64
End of the search window in Unix seconds.
Minimum 0

Responses

200Tempo v2 tag names

Request

curl -G http://traces-reader.telemetry:3200/read/ns/default/api/v2/search/tags \
  -u reader:$PASSWORD \
  --data-urlencode 'q={ resource.service.name = "checkout" && duration > 500ms }' \
  --data-urlencode 'start=1791460800' \
  --data-urlencode 'end=1791464400'

Response · 200

{
  "scopes": [
    {
      "name": "resource",
      "tags": [
        "service.name",
        "k8s.namespace.name"
      ]
    },
    {
      "name": "span",
      "tags": [
        "http.method",
        "http.status_code"
      ]
    }
  ]
}

Resource

ingest

OTLP/HTTP and Zipkin ingestion. OTLP/gRPC and Jaeger gRPC are served on separate ports.

Zipkin spans

POST/write/ns/{namespace}/api/v2/spans

Zipkin v2 JSON span ingestion. Legacy Zipkin reporters rarely retry rejected batches, so put an OpenTelemetry Collector in front when loss is unacceptable.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Request body

application/json

annotationsarray of ZipkinAnnotation | null
›Show child attributesHide child attributes
- timestampinteger · int64required
  Minimum 0
- valuestringrequired
durationinteger · int64 | null
Minimum 0
idstringrequired
localEndpointZipkinEndpoint | null
›Show child attributesHide child attributes
- ipv4string | null
- ipv6string | null
- portinteger · int32 | null
  Minimum 0
- serviceNamestring | null
namestring | null
parentIdstring | null
remoteEndpointZipkinEndpoint | null
›Show child attributesHide child attributes
- ipv4string | null
- ipv6string | null
- portinteger · int32 | null
  Minimum 0
- serviceNamestring | null
tagsmap of string | null
timestampinteger · int64 | null
Minimum 0
traceIdstringrequired

Responses

202Zipkin spans accepted
400Invalid Zipkin requestapplication/json
›ErrorEnvelope
- errorstringrequired

Request

curl -X POST "http://traces-writer.telemetry:3200/write/ns/default/api/v2/spans" \
  -u writer:$PASSWORD \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
[
  {
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "id": "00f067aa0ba902b7",
    "name": "post /pay",
    "timestamp": 1791464400000000,
    "duration": 412000,
    "localEndpoint": {
      "serviceName": "checkout"
    },
    "tags": {
      "http.method": "POST"
    }
  }
]
EOF

OTLP traces

POST/write/ns/{namespace}/v1/traces

OTLP/HTTP ExportTraceServiceRequest, protobuf or JSON. OTLP/gRPC (4317) and Jaeger gRPC (14250) are also served on the pod.

Path parameters

namespacestringrequired
Configured tenant namespace

Request body

application/jsonapplication/x-protobuf

OTLP ExportTraceServiceRequest.

Responses

200OTLP traces accepted
400Invalid OTLP requestapplication/json
›ErrorEnvelope
- errorstringrequired
413Request exceeds configured limit

Request

curl -X POST "http://traces-writer.telemetry:3200/write/ns/default/v1/traces" \
  -u writer:$PASSWORD \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "checkout"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
              "spanId": "00f067aa0ba902b7",
              "name": "POST /pay",
              "kind": 2,
              "startTimeUnixNano": "1791464400000000000",
              "endTimeUnixNano": "1791464400412000000"
            }
          ]
        }
      ]
    }
  ]
}
EOF

Resource

operations

Probes and data source checks.

Liveness

GET/-/healthy

Returns 200 while the process is running. Use it as the Kubernetes liveness probe; it is unprefixed and not namespace-scoped.

Responses

200Process is healthy

Request

curl http://traces-reader.telemetry:3200/-/healthy

Readiness

GET/-/ready

Returns 200 once every storage shard assigned to this pod is open, and 503 while shards are still being acquired or handed off. Use it as the readiness probe.

Responses

200Server is ready
503Assigned shards are not ready

Request

curl http://traces-reader.telemetry:3200/-/ready

Echo

GET/read/ns/{namespace}/api/echo

Tempo-compatible echo used by Grafana to validate the data source.

Path parameters

namespacestringrequired
Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Responses

200Tempo-compatible echo

Request

curl http://traces-reader.telemetry:3200/read/ns/default/api/echo \
  -u reader:$PASSWORD