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

# Observability

> Every run is persisted with its full tool-call trace, token usage, cost, and latency.

Every run - from the playground, the API, a schedule, a channel, or an eval - is
persisted with its inputs, its output, and the ordered sequence of tool calls
and results that produced it.

## Traces

A trace is the run's steps in order: each tool call with its arguments, and the
result that came back. It is the same data live and after the fact, so a run you
watched stream is replayable later without extra instrumentation.

```bash theme={null}
cruqai runs                 # recent runs
cruqai trace <run-id>       # one run's persisted trace
```

In the dashboard this is **AI Monitoring**.

## Metering

Each run records prompt tokens, completion tokens, total tokens, cost in USD,
and wall-clock duration, taken from the provider's own usage block.

```
run       agent     status     created           cost  time  input
1ee3a5fe  69f7142c  completed  2026-08-06 12:05  $0.0031  2.4s  summarise Q3
```

Cost is exact decimal and is carried as a string on the wire - JSON floats
cannot represent it faithfully.

Every metering field is **nullable, and null means unknown**. Some providers
report no usage block; that is not the same as a run that cost nothing. The CLI
prints `-` rather than `$0` so the two cannot be confused, and anything summing
these values can tell them apart.

<Note>
  Eval runs carry `source = "eval"` and are excluded from AI Monitoring and
  `cruqai runs` by default. A single model comparison can add hundreds of rows,
  which would otherwise bury real traffic.
</Note>

## Over the API

```bash theme={null}
GET /v1/runs?agent=<id>&limit=20
GET /v1/runs/{id}          # the run plus its steps
```

Usage is nested under `usage` on each run:

```json theme={null}
{
  "id": "...",
  "status": "completed",
  "model": "openrouter/openai/gpt-4o-mini",
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150,
    "cost_usd": "0.000042",
    "duration_ms": 820
  }
}
```