# agent trace list

List the available trace files that were recorded during all agent preview sessions.

## Description for agent trace list

When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).

Each row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.

## Flags

| Flag Name (Long) | Flag Name (Short) | Description                                                                                                                                                                                                                                                                                                                                        |
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent`        | `-a`              | **Type:** Value<br><br>API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.                                                                                                                              |
| `--flags-dir`    | N/A               | **Type:** Value<br><br>Import flag values from a directory.                                                                                                                                                                                                                                                                                        |
| `--json`         | N/A               | **Type:** Boolean<br><br>Format output as json.                                                                                                                                                                                                                                                                                                    |
| `--session-id`   | N/A               | **Type:** Value<br><br>Session ID used to filter the list of trace files. Use the "agent preview sessions" CLI command to list all known agent preview sessions along with their session IDs.                                                                                                                                                      |
| `--since`        | N/A               | **Type:** Value<br><br>Date used to filter the list of trace files; only those recorded on or after the date are listed.<br><br>Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The "Recorded At" values shown in the table output are valid inputs. |

## Examples for agent trace list

List all trace files for all agents and sessions:

```shell
sf agent trace list
```

List all trace files for a specific agent:

```shell
sf agent trace list --agent My_Agent
```

List trace files for a specific session:

```shell
sf agent trace list --session-id <SESSION_ID>
```

List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):

```shell
sf agent trace list --since 2026-04-20
```

List trace files recorded on or after a specific UTC time:

```shell
sf agent trace list --since 2026-04-20T14:00:00Z
```

Filter by agent and date together:

```shell
sf agent trace list --agent My_Agent --since 2026-04-20
```

Return results as JSON:

```shell
sf agent trace list --json
```