Traces — GET /v1/traces/{id}

The observability plane: one id follows a request across every internal hop. (This is the traces half of the One API's discovery+traces route group — for /v1/discovery/* see plungeai-discovery.)

Auth: Authorization: Bearer ozk_YOUR_KEY on every route here.

GET /v1/traces/{id} — the execution trace

Every response from the API carries a server-minted x-request-id; that id is also a trace id. To correlate multiple calls (or to pick the id yourself), send an x-trace-id header and keep your own copy — it is threaded through every internal hop of every plane, but it is not echoed on the response (only x-request-id is). The header must be a UUID: any other value is ignored and the trace id falls back to that call's x-request-id.

# 1. Execute with your own trace id (a UUID)
TRACE=$(uuidgen | tr 'A-Z' 'a-z')
curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer ozk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "x-trace-id: $TRACE" \
  -d '{"prompt": "Say: traced"}'

# 2. Read the whole story
curl -s https://api.plungeai.com/v1/traces/$TRACE \
  -H "Authorization: Bearer ozk_YOUR_KEY"

{
  "trace_id": "00000000-0000-4000-8000-000000000006",
  "spans": [
    { "id": 101, "trace_id": "00000000-0000-4000-8000-000000000006",
      "workflow_id": "2cecae7f-...", "task_id": null, "ts": 1787706891000,
      "type": "request_received", "agent": null, "status": null,
      "duration_ms": null, "payload_ref": null, "payload_inline": "..." },
    { "id": 102, "trace_id": "00000000-0000-4000-8000-000000000006",
      "workflow_id": "2cecae7f-...", "task_id": "t1", "ts": 1787706891200,
      "type": "task_dispatched", "agent": "one-agent", "status": null,
      "duration_ms": null, "payload_ref": null, "payload_inline": null },
    { "id": 103, "trace_id": "00000000-0000-4000-8000-000000000006",
      "workflow_id": "2cecae7f-...", "task_id": "t1", "ts": 1787706892100,
      "type": "task_completed", "agent": "one-agent", "status": "success",
      "duration_ms": 900, "payload_ref": null, "payload_inline": "traced" },
    { "id": 104, "trace_id": "00000000-0000-4000-8000-000000000006",
      "workflow_id": "2cecae7f-...", "task_id": null, "ts": 1787706892150,
      "type": "workflow_result", "agent": null, "status": "success",
      "duration_ms": 950, "payload_ref": null, "payload_inline": "traced" }
  ],
  "gateway_requests": [
    { "id": "9f2c1e44-...", "trace_id": "00000000-0000-4000-8000-000000000006",
      "plane": "agents", "route": "/v1/agents/:id/execute", "user_id": "u-...",
      "status": 200, "upstream": "cnl-engine", "duration_ms": 1180,
      "cost_usd": null, "created_at": 1787706892 }
  ]
}

Reading it:

Span sequence: request_received → workflow_loaded → workflow_started → task_dispatched → task_completed → workflow_result. A task with retry configured shows duplicate task_dispatched spans on the same task_id.
Payloads: payload_inline is guard-scanned text ≤1KB (secrets/PII come back redacted); larger payloads live behind payload_ref (a storage key, not a URL you can fetch through this API).
gateway_requests is the router's own request log for the same trace id — plane, route, status, upstream, latency, and cost where measured.
Ownership and 404. A trace is readable only by the account that owns it: an id that is unknown, or belongs to another key, is 404 not_found — the same answer for both, so a stranger learns nothing. Spans are written asynchronously: a read right after a request may 404 or come back short for a few seconds. Retry for a short capped while, then stop. The route returns at most the first 500 spans.

Use traces to debug: a 502 engine_error on execute + the trace for that request id shows exactly which hop failed and how long each took. The higher-altitude reads (live SSE events, execution summary, the debugging playbook) live in references/observability.md.