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

# mutagent traces

> Find a session, then read its traces, logs and transcript; query your agents' traces with the same filters Helix uses.

`mutagent traces` reads your agents' traces from Mutagent: the runs of your cloud sessions, and the
traces of a Factory entry wherever the entry's trace source is. Everything is addressed by the Helix
session id, which starts with `hs1_`, or by a trace id.

* `traces sessions` finds a session id.
* `traces agents` lists the agent names seen in traces.
* `traces get --session <hs1_…>` reads every trace of that session.
* `traces list` and `traces count` query traces with filters.
* `traces logs` and `traces transcript` read a session's output and its conversation.

Every command here is a read: run them freely. Traces come back as UniTF, Mutagent's unified trace
format, with a **manifest** that says what was covered.

**Before you start:** [install the CLI](https://docs.mutagent.io/cli/installation.md), [sign in](https://docs.mutagent.io/cli/commands/login.md)
(`MUTAGENT_API_KEY=<key> mutagent login --json` for a coding agent), and select the workspace with
`mutagent workspaces use <workspace-name>`. Pass `--json` for one result object on stdout.

## A worked example

```bash theme={null}
mutagent traces sessions --since 2h --json
mutagent traces get --session hs1_8f2c41d07a --json
mutagent traces count --agent invoice-pricing --since 7d --json
mutagent traces list --agent invoice-pricing --since 24h --has-error --json
```

1. `sessions` lists one row per session. Copy the `hs1_` id of the one you want.
2. `get --session` reads every trace of that session, following its restore chain.
3. `count` sizes the window before a wide list.
4. `list` returns the matching traces, newest first.

## Filters

`traces list` and `traces count` take the same filters.

| Flag | What it matches |
| - | - |
| `--since <when>` | Window start: `10min`, `1h`, `24h`, `3d`, `1w` or ISO-8601. The default is `7d`. |
| `--until <when>` | Window end, in the same forms. The default is now. |
| `--session <session-id>` | One Helix session (`hs1_…`). |
| `--trace <trace-id>` | One trace id. |
| `--agent <id>` | An agent name. For an `Agent` or multi-agent Factory entry, its id. |
| `--skill <id>` | A skill id. For a `Skill` entry, its id. |
| `--workflow <id>` | A workflow id. For a `Workflow` entry, its id. |
| `--query <text>` | Keyword search. |
| `--tag <tag>` | A tag. Repeat it; every tag must match. |
| `--scope <s>` | `any`, `scoped` or `unscoped` (unscoped: single-shot LLM-prompt features). |
| `--has-error` | Only traces with an error. |
| `--has-feedback` | Only traces with feedback. |
| `--score-below <n>` | Only traces scored below `n`. |

> [!NOTE]
>
> In these commands `m` is not minutes. A bare `<n>m`, such as `10m`, is refused with
> `VALIDATION_ERROR` and the fix `Use 10min for minutes or 10d for days`; nothing is sent. Write
> minutes as `min` (`10min`, `30min`) and days as `d`.

There is no `--source` or `--platform`. A Factory entry records where its traces live (Mutagent, or a
connected source such as Langfuse or OpenObserve), and the server reads from there. Find an entry's
traces by its id through `--agent`, `--skill` or `--workflow`.

**The manifest.** A source cannot always apply every filter. A filter it did not apply is named in
`manifest.unapplied` and on stderr, and the result is then a superset: it may hold traces that filter
would have removed. Show `manifest.unapplied` to the person reading the result.

## mutagent traces sessions

The session index: one row per session, with its restore chain. This is how you find a session id.

```bash theme={null}
mutagent traces sessions --since 2h --json
mutagent traces sessions --agent invoice-pricing --origin managed --json
```

| Flag | What it does |
| - | - |
| `--since <when>`, `--until <when>` | The window. The default is the last 7 days. |
| `--agent <id>`, `--skill <id>`, `--workflow <id>` | Only sessions of this agent, skill or workflow (or Factory entry id). |
| `--origin <o>` | Only sessions started from `cli`, `gateway`, `managed` or `web`. |
| `--limit <n>` | Page size, 1 to 200. The default is 50. |
| `--cursor <c>` | The `nextCursor` of the previous page. |

Pass a row's id to `mutagent traces get --session <id>`.

## mutagent traces agents

The agent names seen in traces over a window, with the trace count, when each was last seen, and the
source. It reads the workspace's own traces and its connected pull sources (Langfuse, OpenObserve); a
name seen in both has one row per source.

```bash theme={null}
mutagent traces agents --json
mutagent traces agents --since 7d --json
```

`--since <when>` sets the window start; the default is `24h`. Pass a name to
`mutagent traces list --agent <name>`.

## mutagent traces get

One trace by id, or every trace of one session.

```bash theme={null}
mutagent traces get --session hs1_8f2c41d07a --json
mutagent traces get 4bf92f3577b34da6a3ce929d0e0e4736 --json
```

| Argument or flag | What it does |
| - | - |
| `<trace-id>` | One trace. Not with `--session`. |
| `--session <session-id>` | Every trace of this Helix session, following its restore chain. |

Pass one of the two; both is `INPUT_CONFLICT`. An unknown session is `SESSION_NOT_FOUND`: list them
with `mutagent traces sessions --since 7d`.

## mutagent traces list

Traces that match the [filters](#filters), newest first. `mutagent traces ls` is the same command.

```bash theme={null}
mutagent traces list --agent invoice-pricing --since 24h --has-error --json
mutagent traces list --agent support-bot --since 2026-10-01 --until 2026-10-03 --json
mutagent traces list --workflow invoice-intake --since 7d --json
```

Paging flags, in addition to the filters:

| Flag | What it does |
| - | - |
| `--limit <n>` | Cap the total number of results. |
| `--page-size <n>` | Page size, 1 to 200. The default is 50. |
| `--cursor <c>` | The `nextCursor` of the previous page. |

A source that takes too long answers `SOURCE_TIMEOUT`: narrow the window. The manifest says what was
covered.

## mutagent traces count

How many traces match the [filters](#filters). Run it to size a window before `list`.

```bash theme={null}
mutagent traces count --agent invoice-pricing --since 7d --json
mutagent traces count --workflow invoice-intake --has-error --json
```

## mutagent traces logs

A session's logs: its output stream and its log records, in time order.

```bash theme={null}
mutagent traces logs --session hs1_8f2c41d07a --since 10min --json
mutagent traces logs --session hs1_8f2c41d07a --follow
```

| Flag | What it does |
| - | - |
| `--session <session-id>` | The Helix session. Required on your machine. |
| `--since <when>`, `--until <when>` | The window. |
| `--follow` | Keep reading new lines, polling every 2 seconds, until Ctrl-C. |
| `--limit <n>` | Page size, 1 to 200. The default is 50. |
| `--cursor <c>` | The `nextCursor` of the previous page. |

With `--follow` and `--json`, each log line is one JSON object per line, not one result object. A
coding agent should read pages instead: `--follow` runs until it is stopped.

## mutagent traces transcript

Download a cloud session's transcript, the conversation, as JSONL. It is the newest checkpoint of the
session, as saved.

```bash theme={null}
mutagent traces transcript --session hs1_8f2c41d07a --out /tmp/ses.jsonl --json
mutagent traces transcript --session hs1_8f2c41d07a > ses.jsonl
```

| Flag | What it does |
| - | - |
| `--session <session-id>` | The Helix session. Required on your machine. |
| `--out <file>` | Write to a file. The default is stdout. |

The transcript is the person's conversation: write it to a file with `--out`; a coding agent should
not paste it into chat. A session that has not saved a checkpoint yet answers `TRANSCRIPT_NOT_READY`:
wait for it, or save one with
[`mutagent helix session checkpoint`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-checkpoint).

## In a cloud sandbox

Inside a cloud sandbox the CLI signs in with the sandbox's own token, and `--session` defaults to the
sandbox's own session (`MUTAGENT_SESSION_ID`). So `mutagent traces get --json` reads the session's own
traces with no flags.

A sandbox reads its own session. A session launched for a Factory entry's `evaluate`, `diagnose` or
`optimize` stage may also read that entry's traces. The server derives this from how the session was
launched; there is no flag for it. Anything else is refused with `TRACES_SCOPE`.

## If it fails

| Exit code or error | Fix |
| - | - |
| `3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`) | [Sign in](https://docs.mutagent.io/cli/commands/login.md), then `mutagent workspaces use <workspace-name>`. |
| `2` (`AUTH_EXPIRED`, `INVALID_API_KEY`) | Sign in again, or set a valid `MUTAGENT_API_KEY`. |
| `SESSION_NOT_FOUND` (exit 1) | `mutagent traces sessions` lists the sessions you can read. |
| `MISSING_ARGUMENTS` (exit 1) | Pass `--session <hs1_…>` (or a trace id for `get`). On your machine it has no default. |
| `TRACES_SCOPE` (exit 1) | In a sandbox: read your own session, or the entry this session was launched for. |
| `VALIDATION_ERROR` (exit 1) | Use a window such as `30min`, `2h`, `7d` or ISO-8601 (a bare `10m` is refused: write `10min` or `10d`), and a listed `--scope` or `--origin` value. |

On any other error, run the command in `suggestedAction` once; do not retry blind. See
[CLI errors](https://docs.mutagent.io/cli/errors.md).


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