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, queued, processing, completed, failed) — queued marks an over-quota inbound-email run parked for catch-up, drained as your plan's email rate window frees up
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.

When a model call fails

A failed model step shows the reason on the step itself. Where the cause is something you can change, the message names the setting and the fix rather than repeating the provider's raw response — for example:

The prompt is longer than the model's context window. Trim the prompt template, reduce how much upstream output or knowledge-base context the step receives, add a Transform step to condense it, or choose a model with a larger context window.
A setting the model doesn't accept, such as Temperature on a model that fixes its own sampling. Clear the setting or pick a different model.
A tool the model rejected. Remove the most recently added tool, or switch to a model that supports it.
The provider was rate-limited or overloaded. Nothing is misconfigured — retry, and if it recurs, lower the trigger frequency to spread the work out.
The model is no longer offered by the provider. Pick a different model; this one will disappear from the model list.

Max Tokens is not in this list: a value above the model's output limit is capped automatically rather than failing the run.

Failures we can't attribute to a specific setting show the provider's own message instead, with any credentials removed.

Retention

Trace history has a retention period — 7 days by default, with the first 7 days stored free of charge. It is set on Data Retention → Agent traces in the left navigation, and applies to the account you currently have selected.

Retention deletes trace content permanently. Once a run passes the window:

Its input, each step's input and output, tool-call arguments and results, and any uploaded input files are deleted and cannot be recovered.
The run stops appearing in semantic search over traces.
The run itself stays in the Traces tab, marked expired. Its status, timing, step structure and credit usage remain accurate — only the content is gone.

To keep traces for longer, raise the retention period (days beyond the free 7 are billed as ordinary storage) or set it to Forever. To keep a permanent copy regardless of retention, export the traces before they age out — an export cannot recover content that has already been deleted.

See Data Retention for the full picture: what lowering a window deletes retroactively, how to read the age chart before you save, and what storage costs per day.

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