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

# plungeai-results-traces

> Debug and observe PlungeAI runs: live SSE events, plungeai_get_workflow_status / plungeai_executions history, persisted GET /v1/traces/{id} spans and gateway request cost, the HITL conversation loop (plungeai_continue/plungeai_followup/plungeai_chat), and outbound MCP door runs (POST…


Debug and observe PlungeAI runs: live SSE events, plungeai_get_workflow_status / plungeai_executions history, persisted GET /v1/traces/{id} spans and gateway request cost, the HITL conversation loop (plungeai_continue/plungeai_followup/plungeai_chat), and outbound MCP door runs (POST /v1/mcp/runs), and the REST/MCP/CLI execution verbs (`/v1/executions`: output, continue, followup, steer a running run, files a run produced). Use when a run seems hung, failed, or expensive, when the user wants to correlate calls with x-trace-id, or when resuming a paused ⏸ run. For a run's actual output content use `plungeai-memory`'s SharedMemory section; for authoring the workflow being observed use `plungeai-workflows`.

[Download zip](https://skills.plungeai.com/plungeai-results-traces.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-results-traces/SKILL.md)

Every execution is observable at four altitudes: live events while it runs, a
status/history record after, a persisted span-level trace, and the gateway's own
request log with cost. Read them in this order instead of re-running the workload
to "see what happens."

## Prerequisites

- A self-service `ozk_` API key from **Dashboard → One API → Keys**
  (https://dashboard.plungeai.com), or an MCP client connected to
  `https://mcp.plungeai.com/v1`.
- Always capture the ids a run gives you: `workflow_id`/`execution_id`,
  `request_id`, and your own `x-trace-id`. Without them you are grepping
  timestamps.

## Correlation ids — wire them in from the start

Every One API response echoes a server-minted `x-request-id`; send your own `x-trace-id` header to correlate a
whole multi-call operation. **It must be a UUID**: any other value is ignored, and the trace id is then that
call's `x-request-id` (still traceable). A replayed UUID on an execute route is `409 duplicate_execution_id`.

```bash
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"}'

curl -s https://api.plungeai.com/v1/traces/$TRACE -H "Authorization: Bearer ozk_YOUR_KEY"
```

`GET /v1/traces/{id}` answers `{trace_id, spans, gateway_requests}`. An id that is unknown, or belongs to another
key, is `404 not_found` (the same answer for both). Spans and request logs land a few seconds after the run, so
retry a `404` for a short capped while right after a call, then stop. (`ocean-cli traces get ID` is the CLI spelling.)

## The debugging playbook

1. **Run seems hung** → `plungeai_get_workflow_status` (self-heals stuck rows; may
   return a `continuation` block — the run is waiting on a human, not hung).
2. **Run failed** → status `error_message` → the trace's failing span (`status`,
   `agent`, `duration_ms`).
3. **Output is thin** → execution summary `failed_branches[]` and `tasks_skipped`.
4. **Slow** → per-task durations from SSE events/spans; a staircase against one
   destination means queueing there, not in the engine.
5. **Expensive** → trace `gateway_requests[].cost_usd` by route.
6. **Instructions seemingly ignored** → the run's own warnings (capability ids that
   degraded — `plungeai-skills-plugins`).

Full playbook, execution-summary fields, and quality signals:
[`references/observability.md`](/skills/plungeai-results-traces/references/observability). Full `GET /v1/traces/{id}` shape and error rules:
[`references/traces.md`](/skills/plungeai-results-traces/references/traces).

## The ⏸ human-in-the-loop loop

A run pauses (never dies) on an `ask_user` question or an approval gate, surfaced
as `continuation` on `plungeai_get_workflow_status`. Relay the block verbatim, wait
for the human's words, then:

- `plungeai_continue {execution_id, approve: true}` — ONLY after an explicit yes.
- `plungeai_continue {execution_id, message: "<their words>"}` — anything else.

Never approve on your own, never rephrase the pending action, never retry around a
pause. Once a run is COMPLETE, use `plungeai_followup {execution_id, prompt}`
instead — `continue` on a finished run redirects you there. Free-standing chat with
no run in sight is `plungeai_chat`. Full parameter tables and failure messages:
[`references/conversation.md`](/skills/plungeai-results-traces/references/conversation).

## Executions over REST, MCP and CLI — steer a live run, collect its files

Every run is an execution, whichever door started it (REST, CLI, MCP, Studio, a schedule, a
trigger, a chat). One resource, three spellings:

| Job | REST (`ozk_` key) | MCP `plungeai_executions` / tool | CLI `ocean-cli executions …` |
|---|---|---|---|
| list | `GET /v1/executions?source=&status=&workflow_id=&limit=&offset=` (`status`: `running`, `completed`, `failed`, `cancelled`; limit ≤ 100, default 20) | `list` | `list` |
| poll | `GET /v1/executions/{id}` — `status`, or `needs_input` / `needs_approval` with a `continuation` | `get`, `plungeai_get_workflow_status` | `get`, `status`, `poll` |
| output | `GET …/{id}/output?format=` (`json`, `yaml`, `markdown`, `text`) | `output` | `output` |
| answer or approve a pause | `POST …/{id}/continue {answer \| approve, allow_scope?}` (`once`, `run`, `always`) | `plungeai_continue {message \| approve}` | `continue ID [--message TEXT \| --approve]` |
| talk to a run | `POST …/{id}/followup {text}` (202 queued while running, 200 new turn once done); `GET …/{id}/conversation` | `plungeai_followup {prompt}`; `conversation` | `followup ID PROMPT`; `conversation` |
| **steer a RUNNING run** | `POST …/{id}/steer {text}` — queued for its next turn (202); `409 execution_finished` if over | `steer {execution_id, message}` | `steer ID TEXT` |
| **files the run produced** | `GET …/{id}/files` — spreadsheets, documents, decks | `files` | `files ID` |
| cancel, re-attach, delete | `POST …/{id}/cancel`, `GET …/{id}/stream` (SSE: `status`, `progress`, `done`; `?task=` up to 4), `DELETE …/{id}` | `cancel`, `delete` | `cancel`, `delete` |

`steer` is for a run still in flight (a bot mid-loop that should change course); `followup` on a
finished run starts a new turn in its conversation. A run that reaches its stored spend cap
says so in its result (`[run stopped at $… per-run budget cap …]`). Ids are the `workflow_id` /
`execution_id` of the call that started the run (or its engine id `exec-…`).

What builders get wrong:

- **The message field is spelled three ways**: REST `text` (`followup`, `steer`) and `answer` (`continue`), MCP
  `prompt` (`plungeai_followup`) and `message` (`plungeai_continue`, `steer`), the CLI a positional argument.
- **Another account's id answers `404 execution_not_found`**, like a missing one. A run made for your customer
  (`POST /v1/execute` with `on_behalf_of`) is read with `?on_behalf_of=<customer id>` on `get`, `output` and `files`.
- **`output` has its own states**: `404 not_ready` (still running: poll), `409 execution_failed` (the message is the
  run's error), `410 result_expired`. `continue` on a finished run is `409 not_paused` (use `followup`);
  `410 session_expired` means no conversation session is left.
- A run takes at most 5 live `stream` attachments (`429 too_many_streams`); a finished run is `409 execution_finished`.
- `GET /v1/workflows/results/{workflowId}/{taskId}` and `GET /v1/agents/results/{workflowId}/{taskId}` read one
  task's stored output (`plungeai-memory` has SharedMemory); `POST /v1/workflows/executions/{id}/cancel` is the same
  cancel as `POST /v1/executions/{id}/cancel`. Route detail: `plungeai-api-setup` → `references/bots-and-door.md`.

## Outbound MCP door runs

Separately from the platform's own inbound MCP tools, you can open a metered run
against third-party MCP servers: `POST /v1/mcp/runs {server_ids: [...]}` → call
namespaced tools (`mcp__<server>__<tool>`) → `DELETE` to close. Runs expire after 30
idle minutes, and a closed, expired or unknown run id is `404 run_not_found` (retrying never revives it: open a new
run). Full lifecycle, error shapes, and a working TypeScript pattern: [`references/mcp-runs.md`](/skills/plungeai-results-traces/references/mcp-runs). CLI:
`ocean-cli mcp runs create | tools | call | delete`.

## Gotchas

- Per-task duration is measured from SERVER timestamps in the SSE stream — never
  time a run from your own clock around the request.
- `payload_inline` on a trace span is guard-scanned and capped at 1 KB; larger
  payloads sit behind `payload_ref` (not fetchable through this API).
- A scheduler run id is not directly resolvable by `plungeai_get_workflow_status` /
  `plungeai_get_result` — go through `plungeai_schedule {action: "runs"}` first
  (`plungeai-scheduling`).
- Full `plungeai_get_workflow_status` / `plungeai_executions` parameter and return
  contracts live in `plungeai-workflows` (`references/mcp.md`) — this skill covers
  what to do with them once you have a run's ids.

## Related skills

- `plungeai-workflows` — full `plungeai_get_workflow_status` / `plungeai_executions`
  contracts, and authoring the workflow being observed.
- `plungeai-missions` — mission-specific pause/resume and iteration-cap semantics.
- `plungeai-scheduling` — a scheduled job's own run ledger.
- `plungeai-memory` — SharedMemory (`plungeai_get_result`), a run's actual output.
- `plungeai-skills-plugins` — the capability-resolution warnings this playbook checks.

## Reference

- [`references/observability.md`](/skills/plungeai-results-traces/references/observability) — correlation ids, SSE event order, execution
  summary, the debugging playbook, quality signals.
- [`references/traces.md`](/skills/plungeai-results-traces/references/traces) — full `GET /v1/traces/{id}` route detail.
- [`references/conversation.md`](/skills/plungeai-results-traces/references/conversation) — `plungeai_continue` / `plungeai_followup` /
  `plungeai_chat` and the ⏸ HITL protocol.
- [`references/mcp-runs.md`](/skills/plungeai-results-traces/references/mcp-runs) — outbound MCP door: open/list/call/close a run.

## Reference pages

<CardGroup cols={2}>
<Card title="Conversation — chat, followup, continue (and the ⏸ HITL loop)" icon="file-text" href="/skills/plungeai-results-traces/references/conversation">
Three distinct conversation surfaces — pick by what the user is doing:
</Card>
<Card title="MCP plane — /v1/mcp" icon="file-text" href="/skills/plungeai-results-traces/references/mcp-runs">
Two directions in one plane:
</Card>
<Card title="Observability — watching, debugging, and pricing platform runs" icon="file-text" href="/skills/plungeai-results-traces/references/observability">
Every execution on PlungeAI is observable at four altitudes: live events while it runs, an execution record after it finishes, a persisted span-level trace…
</Card>
<Card title="Traces — GET /v1/traces/{id}" icon="file-text" href="/skills/plungeai-results-traces/references/traces">
The observability plane: one id follows a request across every internal hop.
</Card>
</CardGroup>