Create a single span and return the persisted span.

Use this for one-off span ingestion; to write many spans in one request use POST /v5/spans/batch. When id is omitted the server generates a UUID. Depending on per-account server configuration the span is persisted to Postgres, to the ClickHouse-backed tracing service, or both; when the tracing service is the primary store, a write failure returns a retryable 503 with a Retry-After header.

Retrieve a single span by its id.

The span is read from Postgres or, for accounts migrated to the ClickHouse-backed tracing service, from that service — with automatic fallback to Postgres on error unless the account is in strict mode, where a tracing-service failure surfaces as a 503. Access is authorized against the span's parent trace, so a span in a trace the caller cannot read is rejected; an unknown id returns 404.

Partially update a span's mutable fields and return the updated span.

Only the provided fields among name, end timestamp, output, metadata, and status are changed. This endpoint is available only for accounts still backed solely by Postgres: once an account begins dual-writing to the ClickHouse-backed tracing service — which is upsert-only and has no partial-update operation — PATCH returns 501 and PUT /v5/spans/batch must be used instead. Updates are authorized against the span's parent trace, and an unknown id returns 404.

Create multiple spans (up to 1000) in a single request and return the created spans.

Prefer this over repeated POST /v5/spans calls when ingesting many spans at once; use PUT /v5/spans/batch instead when a span with the same id may already exist, since this endpoint inserts new spans rather than overwriting. A batch larger than 1000 spans is rejected with a validation error. Each item follows the same id-generation and per-account dual-write rules as the single-span create, and when the tracing service is the primary store a write failure returns a retryable 503.

Insert or replace multiple spans (up to 1000) in a single request, keyed by span id.

Use this for idempotent ingestion where a span with the same id may already exist — it will be overwritten — unlike POST /v5/spans/batch, which only inserts. Items without an id are assigned a generated UUID, and duplicate ids within the request are collapsed to the last occurrence. A batch larger than 1000 spans is rejected with a validation error. The write follows the same per-account dual-write rules, and when the tracing service is the primary store a write failure returns a retryable 503.