The ax spans commands are currently in BETA. The API may change without notice. A one-time warning is emitted on first use. The delete command is in ALPHA.
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.
# 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 |
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 |
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
