> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/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, orchestration/api-gateway/routes/traces.ts, orchestration/api-gateway/api-gateway.ts | last-synced: 2026-10-05 (One API 2.3.0: a trace is owner-only, unknown and foreign ids are 404; x-trace-id must be a UUID) -->
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`.

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

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