> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> Everything the agent did on a run, in order. The first place to look when a run surprises you.

`GET /v1/loom/runs/:id/trace` returns the full record of a run: every model call, every tool call, the arguments, the results, the timings, and the cost.

Where the run object tells you *what the agent said*, the trace tells you *what the agent did*.

## Shape

```
run
├─ agent_snapshot        the exact agent spec in force for this run
├─ connection            which host, if any
└─ turns[]               one per model call, in order
   ├─ model_class, input_tokens, output_tokens
   ├─ duration_ms, cost_credits
   ├─ request / response  what we sent the model and got back
   └─ tool_calls[]       what the model decided to do
```

A run has one turn per model call. A turn that decides to use a tool produces a tool call, the result goes back to the model, and the next turn begins. A simple answer is one turn; a run that looks something up, asks a question, and then acts might be four.

## Reading one

Start at the last turn and work backwards — that is where the run ended up. Then:

* **The agent did something you did not expect?** Look at `args` on the tool call. The model's decision is visible there before your endpoint is involved.
* **Your endpoint returned something odd?** `request` on the tool call is the egress we actually made, headers and body.
* **The run cost more than you expected?** `input_tokens` per turn usually explains it — long context or many tool round-trips.
* **The agent ignored an instruction?** `agent_snapshot` shows the spec that actually ran, which may not be the agent as it stands now.

## Snapshots make old traces truthful

Because the spec is captured at run start, editing an agent does not rewrite history. A trace from last week shows the instructions that were in force last week. When you are reconstructing an incident, that is the difference between an answer and a guess.

## Redaction

Fields a [patch](/guides/patches) declares as redacted never reach the trace. What you see is the redacted form; the original was never stored.

## Cost

Every turn carries `cost_credits`, and the run totals them. Credits are charged on model usage — input and output tokens, priced by model class — plus any priced patches the run used. See [Rate limits and credits](/guides/limits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.