Skip to main content
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, sign in (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

  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.
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.
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.
--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.
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, newest first. mutagent traces ls is the same command.
Paging flags, in addition to the filters: 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. Run it to size a window before list.

​
mutagent traces logs

A session’s logs: its output stream and its log records, in time order.
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.
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.

​
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

On any other error, run the command in suggestedAction once; do not retry blind. See CLI errors.