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

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.

Reference pages