---
name: plungeai-results-traces
description: "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). 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`."
---

# PlungeAI Results & Traces — observing and debugging runs

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. If you never sent
one, the trace id IS that call's `x-request-id` — still traceable:

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

curl -s https://api.plungeai.com/v1/traces/my-batch-2026-08-27-001 \
  -H "Authorization: Bearer ozk_YOUR_KEY"
```

An unknown/lagging trace id returns `200` with empty arrays, never `404` — poll
until `spans` is non-empty (with a cap), don't wait for a 404.

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

## 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. Full lifecycle, error shapes, and a working TypeScript pattern:
`references/mcp-runs.md`.

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