Traces

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

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.

ax traces list <project-id> [--space <id>] [--start-time <time>] [--end-time <time>] [--filter <expr>] [--limit <n>] [--cursor <cursor>] [--output <fmt>] [--verbose]

Option	Description
`project-id`	Project name or ID (required, positional argument)
`--space`, `-s`	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`, `-l`	Maximum number of traces to return (default: 15)
`--cursor`, `-c`	Pagination cursor for the next page
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples:

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.

ax traces export <project-id> [--filter <expr>] [--space <id>] [--days <n>] [--start-time <time>] [--end-time <time>] [--limit <n>] [--output-dir <path>] [--stdout] [--all] [--verbose]

Option	Description
`project-id`	Project name or ID (required, positional argument; name requires `--space` or use with `--all`)
`--filter`	Filter expression applied to the initial span lookup (e.g. `"status_code = 'ERROR'"`)
`--space`, `-s`	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`, `-l`	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`
`--verbose`, `-v`	Enable verbose logs

Examples:

# 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'

API reference

API clients

`ax traces list`

`ax traces export`

​ax traces list

​ax traces export

`ax traces list`

`ax traces export`