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

# Spans

> Export span data with the AX CLI

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

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.

```bash theme={null}
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`     |

<Note>
  `--trace-id`, `--span-id`, and `--session-id` are mutually exclusive. Only one may be provided per invocation.
</Note>

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
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) |

**Examples:**

```bash theme={null}
ax spans annotate proj_abc123 --file ./annotations.jsonl
ax spans annotate my-project --space sp_abc123 --file ./annotations.json --days 7
```