Traces API

Ingest, list, fetch, and tail traces. The single most-used surface in obsrv.

POST /v1/traces

Commit a new trace. Returns immediately after acceptance.

{
  "name": "checkout",
  "run_type": "prod",
  "metadata": { "user_id": "u_a72c", "release": "v3.2.1" },
  "steps": [
    {
      "name": "plan",
      "type": "llm",
      "model": "claude-sonnet-4-6",
      "messages": [
        { "role": "user", "content": [{ "type": "text", "text": "Buy milk" }] }
      ],
      "token_usage": { "input": 900, "output": 120 }
    }
  ]
}

GET /v1/traces

Filter, sort, and paginate the trace feed.

GET /v1/traces?status=error&run_type=prod&model=claude-sonnet-4-6&meta_key=release&meta_value=v3.2.1&limit=50
x-api-key: tk_live_…

GET /v1/traces/:id

Returns the full persisted trace, including steps, messages, attachments, and metadata.

GET /v1/traces/tail

Server-Sent Events stream of new trace IDs. Reconnect with Last-Event-ID.

GET /v1/traces/tail
x-api-key: tk_live_…
Accept: text/event-stream

← Overview

Steps →