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

# Traces

> Query and export trace data with the AX CLI

<Note>
  The `ax traces` commands are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

The `ax traces` commands let you retrieve and export trace data from your Arize projects.

## `ax traces list`

List traces (root spans) within a project.

```bash theme={null}
ax traces list <project-id> [--space <id>] [--start-time <time>] [--end-time <time>] [--filter <expr>] [--limit <n>] [--cursor <cursor>]
```

| Option         | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| `project-id`   | Project name or ID (required, positional argument)                                     |
| `--space`      | Space name or ID (required when using a project name instead of ID)                    |
| `--start-time` | Start of time window, inclusive (ISO 8601, e.g. `2024-01-01T00:00:00Z`)                |
| `--end-time`   | End of time window, exclusive (ISO 8601, e.g. `2024-01-02T00:00:00Z`). Defaults to now |
| `--filter`     | Filter expression (e.g. `"status_code = 'ERROR'"`, `"latency_ms > 1000"`)              |
| `--limit`      | Maximum number of results to return (default: 15)                                      |
| `--cursor`     | Pagination cursor for the next page                                                    |

**Examples:**

```bash theme={null}
ax traces list proj_abc123
ax traces list proj_abc123 --output traces.json
ax traces list proj_abc123 --filter "latency_ms > 2000" --output traces.parquet
ax traces list my-project --space sp_abc123 --limit 50
```

## `ax traces export`

Export full traces — all spans belonging to each matching trace. Uses a two-phase approach: first finds root spans matching the filter, then fetches every span for those traces.

```bash theme={null}
ax traces export <project> [--filter <expr>] [--space <id>] [--days <n>] [--start-time <time>] [--end-time <time>] [--limit <n>] [--output-dir <path>] [--stdout] [--all]
```

| Option         | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `project`      | Project name or ID (required, positional argument)                                    |
| `--filter`     | Filter expression applied to the initial span lookup (e.g. `"status_code = 'ERROR'"`) |
| `--space`      | Space name or ID (required when using a project name or `--all`)                      |
| `--days`       | Lookback window in days (default: 30)                                                 |
| `--start-time` | Override start of time window (ISO 8601)                                              |
| `--end-time`   | Override end of time window (ISO 8601)                                                |
| `--limit`      | Maximum number of traces to export (default: 50, ignored with `--all`)                |
| `--output-dir` | Directory to write the output file (default: current directory)                       |
| `--stdout`     | Print JSON to stdout instead of saving to a file                                      |
| `--all`        | Use Arrow Flight for bulk export — streams all matching spans, ignores `--limit`      |

**Examples:**

```bash theme={null}
# Export the last 30 days of traces for a project
ax traces export proj_abc123

# Export error traces only
ax traces export proj_abc123 --filter "status_code = 'ERROR'"

# Export traces from a specific time range
ax traces export proj_abc123 --start-time 2024-01-01T00:00:00Z --end-time 2024-02-01T00:00:00Z

# Bulk export via Arrow Flight
ax traces export my-project --all --space sp_abc123

# Print to stdout for use in a pipeline
ax traces export proj_abc123 --stdout | jq 'length'
```