Spans

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

The ax spans commands let you export span data from your Arize projects.

`ax spans export`

Export spans to a JSON file. Filter by trace ID, span ID, or session ID (mutually exclusive), and optionally combine with --filter for additional narrowing. Without any ID flag, all spans matching the time window are exported.

ax spans export <project> [--trace-id <id>] [--span-id <id>] [--session-id <id>] [--filter <expr>] [--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)
`--trace-id`	Filter to spans belonging to a specific trace
`--span-id`	Filter to a specific span
`--session-id`	Filter to spans in a specific session
`--filter`	Additional filter expression (e.g. `"status_code = 'ERROR'"`, `"latency_ms > 1000"`)
`--space`, `-s`	Space ID (required when using `--all` for Arrow Flight export)
`--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 spans to export (default: 100, 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

--trace-id, --span-id, and --session-id are mutually exclusive. Only one may be provided per invocation.

Examples:

# Export the last 30 days of spans for a project
ax spans export proj_abc123

# Export spans for a specific trace
ax spans export proj_abc123 --trace-id abc123def456

# Export error spans with a filter
ax spans export proj_abc123 --filter "status_code = 'ERROR'" --limit 200

# Export spans for a specific session
ax spans export my-project --session-id sess_xyz --space sp_abc123

# Bulk export via Arrow Flight (all spans, no limit)
ax spans export my-project --all --space sp_abc123

# Print to stdout for use in a pipeline
ax spans export proj_abc123 --stdout | jq '.[0]'

`ax spans annotate`

Annotate a batch of spans in a project. Provide annotations via --file (JSON, JSONL, CSV, or Parquet; use - for stdin). Each record must have a record_id (the span ID) and values (a list of annotation dicts with at least name, plus optionally score, label, or text). Annotations are upserted; up to 1000 spans may be annotated per request. If any span ID is not found within the time window, the entire request is rejected.

ax spans annotate <project> --file <path> [--space <id>] [--start-time <time>] [--end-time <time>] [--days <n>]

Option	Description
`project`	Project name or ID (required, positional argument)
`--file`, `-f`	Path to a file containing annotation records (JSON, JSONL, CSV, Parquet), or `-` for stdin
`--space`, `-s`	Space name or ID (required when using a project name instead of ID)
`--start-time`	Start of span lookup window (ISO 8601). If omitted, the server default applies
`--end-time`	End of span lookup window (ISO 8601). Defaults to now
`--days`	Lookback window in days (alternative to `--start-time`; ignored when `--start-time` is set)
`--verbose`, `-v`	Enable verbose logs

Examples:

ax spans annotate proj_abc123 --file ./annotations.jsonl
ax spans annotate my-project --space sp_abc123 --file ./annotations.json --days 7

`ax spans delete`

Permanently delete spans by ID. This operation is irreversible. Spans not found within the supported lookback window are silently ignored.

ax spans delete <project> --span-id <id> [--span-id <id> ...] [--space <id>] [--force]

Option	Description
`project`	Project name or ID (required, positional argument)
`--span-id`	Span ID to delete. Repeat the flag (`--span-id id1 --span-id id2`) or pass comma-separated values (`--span-id id1,id2,id3`). At least one is required.
`--space`, `-s`	Space name or ID (required when using a project name instead of ID)
`--force`, `-f`	Skip the confirmation prompt
`--verbose`, `-v`	Enable verbose logs

Examples:

ax spans delete proj_abc123 --span-id span_xyz789 --force
ax spans delete my-project --space sp_abc123 --span-id id1 --span-id id2 --force
ax spans delete proj_abc123 --span-id id1,id2,id3 --force

API reference

API clients

`ax spans export`

`ax spans annotate`

`ax spans delete`

​ax spans export

​ax spans annotate

​ax spans delete

`ax spans export`

`ax spans annotate`

`ax spans delete`