> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

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


<!-- sources-of-truth: orchestration/api-gateway/openapi.ts, docs/ONE-API-DEVELOPER-GUIDE-2.0.md | last-synced: 2026-09-24 -->
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).

```bash
# 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"
```

```json
{
  "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`](/skills/plungeai-results-traces/references/observability).