# div traces

> List the org's traces, newest first, with duration, spans, tokens and errors.

## Synopsis

```text
div traces [flags]
```

Lists the org's traces, newest first by when tracing received them. Needs the `traces:read` scope. Keys from [`div login`](https://docs.divergentlabs.xyz/compute/cli/login.md) have it.

## Flags

| Flag | Description | Default |
| --- | --- | --- |
| `--since <time>` | Only traces received after this time: a time ago (`30m`, `1h`, `7d`), a date (`2026-10-12`) or an ISO 8601 time. | all |
| `--until <time>` | Only traces received before this time, in the same forms. | now |
| `--name <name>` | Only traces with this root span name. | all |
| `--session <id>` | Only traces with this session id. | all |
| `--user <id>` | Only traces with this user id. | all |
| `--environment <env>` | Only traces from this `deployment.environment`. | all |
| `--service <name>` | Only traces with a span from this `service.name`. | all |
| `--model <model>` | Only traces with a span that called this model, such as `gpt-4o-mini`. | all |
| `--errors` | Only traces with a span that ended in an error. | |
| `--score <check>` | Only traces with a score that passes, such as `helpfulness>=0.5` or `verdict==good`. See [Find traces by score](https://docs.divergentlabs.xyz/tracing/guides/scores.md#find-traces-by-score). | |
| `--limit <n>` | Maximum number of traces. Maximum 200. | `50` |
| `--before <trace>` | The page after this trace, as the last line of the previous page says. | |
| `--json` | Print the page as JSON, with `data`, `older` and `newer`. | |
| `--token <key>` | API key to use. | see [Configuration](https://docs.divergentlabs.xyz/compute/cli/configuration.md) |
| `--api-url <url>` | API URL to use. | see [Configuration](https://docs.divergentlabs.xyz/compute/cli/configuration.md) |

## Output

One trace per line on stdout, with no header: trace id, start time in UTC, duration, spans, tokens in→out, name, and the number of error spans if any. `—` means the trace reported none. When there are more traces, stderr gets the command for the next page.

```text
4bf92f3577b34da6a3ce929d0e0e4736  2026-10-12 13:32:36   1.2s  6 spans  42→14  answer question
a3ce929d0e0e47364bf92f3577b34da6  2026-10-12 13:31:02  310ms  2 spans  21→7   chat  1 error
More: div traces --before a3ce929d0e0e47364bf92f3577b34da6
```

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success, including when no traces match. |
| `1` | The API rejected the request. |
| `2` | Invalid flags, such as a `--since` that is not a time. |

## Examples

```bash
div traces --since 1h
div traces --errors --environment production
div traces --model gpt-4o-mini --since 1h
div traces --score 'helpfulness<0.5' --since 7d
div traces --session sess-42 --json
div traces --errors | cut -d' ' -f1 | head -1 | xargs div trace
```