The ax spans commands are currently in ALPHA. The API may change without notice. A one-time warning is emitted on first use.
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 | 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 |
--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) |
ax spans annotate proj_abc123 --file ./annotations.jsonl
ax spans annotate my-project --space sp_abc123 --file ./annotations.json --days 7
