Skip to main content

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.

The ax spans commands are currently in ALPHA. 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]
OptionDescription
projectProject name or ID (required, positional argument)
--trace-idFilter to spans belonging to a specific trace
--span-idFilter to a specific span
--session-idFilter to spans in a specific session
--filterAdditional filter expression (e.g. "status_code = 'ERROR'", "latency_ms > 1000")
--space, -sSpace ID (required when using --all for Arrow Flight export)
--daysLookback window in days (default: 30)
--start-timeOverride start of time window (ISO 8601)
--end-timeOverride end of time window (ISO 8601)
--limitMaximum number of spans to export (default: 100, ignored with --all)
--output-dirDirectory to write the output file (default: current directory)
--stdoutPrint JSON to stdout instead of saving to a file
--allUse 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.
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>]
OptionDescription
projectProject name or ID (required, positional argument)
--file, -fPath to a file containing annotation records (JSON, JSONL, CSV, Parquet), or - for stdin
--space, -sSpace name or ID (required when using a project name instead of ID)
--start-timeStart of span lookup window (ISO 8601). If omitted, the server default applies
--end-timeEnd of span lookup window (ISO 8601). Defaults to now
--daysLookback window in days (alternative to --start-time; ignored when --start-time is set)
Examples: 
ax spans annotate proj_abc123 --file ./annotations.jsonl
ax spans annotate my-project --space sp_abc123 --file ./annotations.json --days 7