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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# ambral traces

> List and read the org's recorded sessions

List and read the org's recorded sessions

Every ambral command also takes the [global flags](https://docs.ambral.ai/cli/reference/global-flags.md).

## ambral traces list

```text theme={null}
ambral traces list [flags] [<workload>]
```

List the org's recorded traces, or one workload's, newest first, a page at a time with how many there are: each one's id, session, end user, steps, the tools it called, its labels and its first user message

| Argument | Takes | Description |
| - | - | - |
| `<workload>` | string; optional | Only this workload's traces |

| Flag | Takes | Description |
| - | - | - |
| `--end-user` | string | Only the sessions that served this end user, by the id your agent sends for them |
| `--label` | string; repeatable | Only those labelled so: `k=v` for that value, `k` for any value; repeat it, and each must hold |
| `--since` | date | Only traces recorded at or after this date or time, UTC (`2026-11-01`, `2026-11-01T09:00`) |
| `--sort` | `newest` \| `oldest` | The order: `newest` first (the default) or `oldest` first |
| `--cursor` | string | Start after this trace: the `next` an earlier page printed, with the same flags |

**Examples**

```sh theme={null}
# Check that an agent's sessions are recorded
ambral traces list support-agent

# One end user's sessions, across every workload
ambral traces list --end-user cus_81723

# Only the sessions production sent, labelled env=prod (a suite's sessions are its runs')
ambral traces list support-agent --label env=prod

# As JSON, with each page's `next`
ambral traces list support-agent --json
```

## ambral traces get

```text theme={null}
ambral traces get [flags] <trace>
```

Show a recorded trace whole: what was recorded about it, and every message of each branch, the latest first, each named `tr_…:<leaf>`, each reply with its model, finish reason, tokens and latency, and each failed call where it happened; or, given one of those names, only that branch

| Argument | Takes | Description |
| - | - | - |
| `<trace>` | string | The trace's id, as `ambral traces list` shows it (tr\_…), or one of its branches, as this command names them (tr\_…:\<leaf>) |

| Flag | Takes | Description |
| - | - | - |
| `--raw` | | Print the trace as stored, every node and call, as JSON in verifiers' trace format, which verifiers loads. It is the whole trace, so name the trace (tr\_…), not a branch. Its `id` is the recording key, not tr\_… |

**Examples**

```sh theme={null}
# The whole session as JSON, to save and read
ambral traces get tr_3f9a0c1b7e22a5d4 --json

# Only the branch ending at node 17
ambral traces get tr_3f9a0c1b7e22a5d4:17

# The whole trace as stored, in verifiers' trace format
ambral traces get tr_3f9a0c1b7e22a5d4 --raw > trace.json
```


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