# 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](https://seclai.com/docs/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](https://seclai.com/docs/governance) 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](https://seclai.com/docs/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](https://seclai.com/docs/prompt-scanner#output-scanning))
- **Governance evaluation results** — if [governance](https://seclai.com/docs/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](https://seclai.com/docs/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](https://seclai.com/docs/agent-steps/control#if-else-step) and [Switch](https://seclai.com/docs/agent-steps/control#switch-step) 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: 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

1. Open the most recent failed trace for an agent.
2. Inspect the first step with a failed status.
3. Review that step's inputs, outputs, and error message.
4. Update the relevant step, prompt, model, or metadata.
5. 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](https://seclai.com/docs/export-formats#agent-traces) for the full file schema and available filter options.

## Next Steps

- [Agents](https://seclai.com/docs/agents) — Understand agent architecture and execution model
- [Agent Steps](https://seclai.com/docs/agent-steps) — Learn each step type and its configuration
- [Agent Triggers](https://seclai.com/docs/agent-triggers) — Control when and how runs start
- [Agent Evaluations](https://seclai.com/docs/agent-evaluations) — Measure output quality and reliability
- [Troubleshooting](https://seclai.com/docs/troubleshooting) — Resolve common runtime issues