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 /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 (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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 (opens in a new tab)), 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.

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

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).
Run failed → status error_message → the trace's failing span (status, agent, duration_ms).
Output is thin → execution summary failed_branches[] and tasks_skipped.
Slow → per-task durations from SSE events/spans; a staircase against one destination means queueing there, not in the engine.
Expensive → trace gateway_requests[].cost_usd by route.
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. Full GET /v1/traces/{id} shape and error rules: references/traces.md.

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.

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

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 — correlation ids, SSE event order, execution summary, the debugging playbook, quality signals.
references/traces.md — full GET /v1/traces/{id} route detail.
references/conversation.md — plungeai_continue / plungeai_followup / plungeai_chat and the ⏸ HITL protocol.
references/mcp-runs.md — outbound MCP door: open/list/call/close a run.

Reference pages

Conversation — chat, followup, continue (and the ⏸ HITL loop)

Three distinct conversation surfaces — pick by what the user is doing:

MCP plane — /v1/mcp

Two directions in one plane:

Observability — watching, debugging, and pricing platform runs

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…

Traces — GET /v1/traces/{id}

The observability plane: one id follows a request across every internal hop.