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

# Experiments

> Manage experiments with the AX CLI

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

The `ax experiments` commands let you create, retrieve, and manage experiments on the Arize platform.

## `ax experiments list`

List all experiments, optionally filtered by dataset.

```bash theme={null}
ax experiments list [--dataset <name-or-id>] [--space <id>] [--limit <n>] [--cursor <cursor>]
```

| Option      | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `--dataset` | Filter experiments by dataset name or ID                            |
| `--space`   | Space name or ID (required when using a dataset name instead of ID) |
| `--limit`   | Maximum number of results to return (default: 15)                   |
| `--cursor`  | Pagination cursor for the next page                                 |

**Example:**

```bash theme={null}
ax experiments list --dataset ds_xyz789
ax experiments list --dataset my-eval-set --space my-space
```

## `ax experiments create`

Create a new experiment from a local file. The file must contain `example_id` and `output` columns. Extra columns are passed through as additional fields.

```bash theme={null}
ax experiments create --name <name> --dataset <name-or-id> --file <path>
```

| Option          | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| `--name`, `-n`  | Name for the new experiment                                                                 |
| `--dataset`     | Dataset name or ID to attach the experiment to                                              |
| `--file`, `-f`  | Path to the data file (CSV, JSON, JSONL, or Parquet) with experiment runs, or `-` for stdin |
| `--space`, `-s` | Space name or ID (required when using a dataset name instead of ID)                         |

**Example:**

```bash theme={null}
ax experiments create --name "my-experiment" --dataset ds_xyz789 --file ./runs.csv
```

## `ax experiments get`

Retrieve an experiment by name or ID.

```bash theme={null}
ax experiments get <name-or-id> [--dataset <name-or-id>] [--space <id>]
```

| Option      | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `--dataset` | Dataset name or ID (required when using an experiment name instead of ID) |
| `--space`   | Space name or ID (required when using a dataset name instead of ID)       |

**Examples:**

```bash theme={null}
ax experiments get exp_abc123
ax experiments get my-experiment --dataset my-eval-set --space my-space
```

## `ax experiments delete`

Delete an experiment.

```bash theme={null}
ax experiments delete <name-or-id> [--dataset <name-or-id>] [--space <id>] [--force]
```

| Option      | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `--dataset` | Dataset name or ID (required when using an experiment name instead of ID) |
| `--space`   | Space name or ID (required when using a dataset name instead of ID)       |
| `--force`   | Skip the confirmation prompt                                              |

**Examples:**

```bash theme={null}
ax experiments delete exp_abc123
ax experiments delete my-experiment --dataset my-eval-set --space my-space --force
```

## `ax experiments export`

Export runs from an experiment to a JSON file.

```bash theme={null}
ax experiments export <name-or-id> [--dataset <name-or-id>] [--space <id>] [--output-dir <path>] [--stdout] [--all]
```

| Option         | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| `--dataset`    | Dataset name or ID (required when using an experiment name instead of ID) |
| `--space`      | Space name or ID (required when using a dataset name instead of ID)       |
| `--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 runs                       |

**Examples:**

```bash theme={null}
ax experiments export exp_abc123
ax experiments export my-experiment --dataset my-eval-set --space my-space --output-dir ./exports
ax experiments export exp_abc123 --all
ax experiments export exp_abc123 --stdout | jq 'length'
```

## `ax experiments annotate-runs`

Annotate a batch of runs in an experiment. Provide annotations via `--file` (JSON, JSONL, CSV, or Parquet; use `-` for stdin). Each record must have a `record_id` (the experiment run ID) and `values` (a list of annotation dicts with at least `name`, plus optionally `score`, `label`, or `text`). Annotations are upserted; up to 1000 runs may be annotated per request.

```bash theme={null}
ax experiments annotate-runs <name-or-id> --file <path> [--dataset <name-or-id>] [--space <id>]
```

| Option      | Description                                                                                |
| ----------- | ------------------------------------------------------------------------------------------ |
| `--file`    | Path to a file containing annotation records (JSON, JSONL, CSV, Parquet), or `-` for stdin |
| `--dataset` | Dataset name or ID (required to resolve the experiment by name)                            |
| `--space`   | Space name or ID (required when using a dataset name instead of ID)                        |

**Examples:**

```bash theme={null}
ax experiments annotate-runs exp_abc123 --file ./annotations.jsonl
ax experiments annotate-runs my-experiment --dataset my-eval-set --space my-space --file ./annotations.json
```