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).

# 1. Execute with your own trace id
curl -s -X POST https://api.plungeai.com/v1/agents/llm-agent/execute \
  -H "Authorization: Bearer ozk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "x-trace-id: my-batch-2026-08-27-001" \
  -d '{"prompt": "Say: traced"}'

# 2. Read the whole story
curl -s https://api.plungeai.com/v1/traces/my-batch-2026-08-27-001 \
  -H "Authorization: Bearer ozk_YOUR_KEY"

{
  "trace_id": "my-batch-2026-08-27-001",
  "spans": [
    { "id": 101, "trace_id": "my-batch-2026-08-27-001",
      "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": "my-batch-2026-08-27-001",
      "workflow_id": "2cecae7f-...", "task_id": "t1", "ts": 1787706891200,
      "type": "task_dispatched", "agent": "llm-agent", "status": null,
      "duration_ms": null, "payload_ref": null, "payload_inline": null },
    { "id": 103, "trace_id": "my-batch-2026-08-27-001",
      "workflow_id": "2cecae7f-...", "task_id": "t1", "ts": 1787706892100,
      "type": "task_completed", "agent": "llm-agent", "status": "success",
      "duration_ms": 900, "payload_ref": null, "payload_inline": "traced" },
    { "id": 104, "trace_id": "my-batch-2026-08-27-001",
      "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": "my-batch-2026-08-27-001",
      "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.
An unknown or still-lagging trace id returns 200 with empty arrays, never 404 — don't poll for a 404, poll until spans is non-empty (with a cap). Spans are written asynchronously and a read immediately after a request may lag by a few seconds; 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.

Traces — GET /v1/traces/{id}

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

Planned: TI-33

Planned: TI-34