Agent Traces

Agent traces are the per-run execution history for an agent. Every run creates a trace that records what happened from start to finish.

What Are Agent Traces?

A trace is a structured execution record for a single run. It helps you understand:

Whether the run succeeded or failed
Which step produced which output
Where errors happened and why
How long each step took
How many credits were consumed

If you want to answer "what happened during this run?", traces are the source of truth.

Where to Find Agent Traces

You can view traces in the UI and query run data via the API.

Per-agent path: Account → Agents → [Agent Name] → Traces
Account-wide path: Dashboard → Agents Tab → All Traces

Use the per-agent Traces tab when you need step-by-step detail for a single agent. Use the Dashboard's All Traces section when you need to search, filter, or compare runs across multiple agents — for example, to spot cross-agent failures or run retroactive governance evaluations on a selection of runs.

What Traces Include

Typical trace details include:

Run status (pending, processing, completed, failed)
Step-level status and execution order
Step input and output payloads
Error messages and failure context
Duration and timing data
Credit usage per run and per step
Prompt scan results — an Input Scan pseudo-step appears as the first entry, showing whether the input passed or failed (see Prompt Scanner)
Output scan results — Output Scan pseudo-steps appear after steps that fetch external data (Web Fetch, Web Search, Webhook Call), showing whether the fetched content was flagged for prompt injection (see Prompt Scanner → Output Scanning)
Governance evaluation results — if governance policies are active, governance evaluation pseudo-steps appear alongside the steps they screened, showing the verdict (pass/flag/block), confidence score, and policy name
Agent evaluation results — if agent evaluations are configured, evaluation pseudo-steps appear after the step they assessed, showing pass/fail status, score, and whether retries were triggered
Branch markers — If / Else and Switch step trace cards render a "Chosen branch" badge naming which branch ran (then / else for If / Else; the matched case name, else, or no match for Switch). Steps inside the un-taken branch appear with skipped status and the post-branch continuation chain (the branching step's own child_steps) appears after the chosen branch with its inherited input.

Figure 1.Complete trace view with input scan, output scan, blocking governance, and agent evaluation — all visible as distinct nodes in the execution graph.

Why Agent Traces Matter

Traces are designed for operational visibility and confidence. They are most useful for:

Debugging: Find the exact failing step and error details
Validation: Confirm outputs match expectations
Performance tuning: Identify slow steps and bottlenecks
Cost monitoring: See credit usage over time
Auditability: Keep a reliable record of run behavior

Common Workflows

Open the most recent failed trace for an agent.
Inspect the first step with a failed status.
Review that step's inputs, outputs, and error message.
Update the relevant step, prompt, model, or metadata.
Re-run the agent and compare the new trace.

This loop makes troubleshooting fast and repeatable.

Exporting

Export an agent's trace history as a downloadable file. Supported formats are JSON and JSONL.

UI: Open the agent's Traces tab and click the Export button. You'll see an estimate of the export size before confirming.
API: POST /authenticated/resource-exports with resource_type: "agent_traces" and the agent ID.
MCP: Use the create_resource_export tool with resource_type: "agent_traces".

Exports include run status, step-level inputs/outputs, errors, timing, and credit usage for each run.

See Export Formats → Agent Traces for the full file schema and available filter options.

Next Steps

Agents — Understand agent architecture and execution model
Agent Steps — Learn each step type and its configuration
Agent Triggers — Control when and how runs start
Agent Evaluations — Measure output quality and reliability
Troubleshooting — Resolve common runtime issues