Experiments

The ax experiments commands are currently in BETA. The API may change without notice. A one-time warning is emitted on first use. The ax experiments run command is stable.

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.

ax experiments list [--dataset <name-or-id>] [--space <id>] [--limit <n>] [--cursor <cursor>] [--output <fmt>] [--verbose]

Option	Description
`--dataset`	Filter experiments by dataset name or ID
`--space`, `-s`	Space name or ID (required when using a dataset name instead of ID)
`--limit`, `-l`	Maximum number of experiments to return (default: 15)
`--cursor`, `-c`	Pagination cursor for the next page
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Example:

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.

ax experiments create --name <name> --dataset <name-or-id> --file <path> [--space <id>] [--output <fmt>] [--verbose]

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)
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Example:

ax experiments create --name "my-experiment" --dataset ds_xyz789 --file ./runs.csv

`ax experiments get`

Retrieve an experiment by name or ID.

ax experiments get <name-or-id> [--dataset <name-or-id>] [--space <id>] [--output <fmt>] [--verbose]

Option	Description
`--dataset`	Dataset name or ID (required when using an experiment name instead of ID)
`--space`, `-s`	Space name or ID (required when using a dataset name instead of ID)
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples:

ax experiments get exp_abc123
ax experiments get my-experiment --dataset my-eval-set --space my-space

`ax experiments run`

Run an experiment task against a dataset and upload results. The task file must define a top-level task function that accepts a dataset example and returns the task output.

ax experiments run --name <name> --dataset <name-or-id> --task <path> [--space <id>] [--concurrency <n>] [--dry-run] [--output <fmt>] [--verbose]

Option	Description
`--name`, `-n`	Experiment name
`--dataset`	Dataset name or ID to run the experiment against
`--task`	Path to a Python file defining a top-level `task` function that accepts a dataset example and returns the task output
`--space`, `-s`	Space name or ID (required when using a dataset name instead of ID)
`--concurrency`, `-c`	Number of concurrent task executions (default: 3)
`--dry-run`	Run the task locally without uploading results to Arize. Processes only the first 10 examples.
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Task file format:

def task(dataset_row) -> str:
    return my_llm_call(dataset_row["question"])

The function receives a dataset example and must return a JSON-serialisable value. Use --dry-run to validate locally before uploading. Examples:

ax experiments run --name "my-experiment" --dataset ds_xyz789 --task ./task.py
ax experiments run --name "my-experiment" --dataset my-eval-set --space my-space --task ./task.py --concurrency 10
ax experiments run --name "my-experiment" --dataset ds_xyz789 --task ./task.py --dry-run

`ax experiments delete`

Delete an experiment.

ax experiments delete <name-or-id> [--dataset <name-or-id>] [--space <id>] [--force] [--verbose]

Option	Description
`--dataset`	Dataset name or ID (required when using an experiment name instead of ID)
`--space`, `-s`	Space name or ID (required when using a dataset name instead of ID)
`--force`, `-f`	Skip the confirmation prompt
`--verbose`, `-v`	Enable verbose logs

Examples:

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.

ax experiments export <name-or-id> [--dataset <name-or-id>] [--space <id>] [--output-dir <path>] [--stdout] [--all] [--verbose]

Option	Description
`--dataset`	Dataset name or ID (required when using an experiment name instead of ID)
`--space`, `-s`	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
`--verbose`, `-v`	Enable verbose logs

Examples:

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.

ax experiments annotate-runs <name-or-id> [--file <path>] [--dataset <name-or-id>] [--space <id>] [--verbose]

Option	Description
`--file`, `-f`	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`, `-s`	Space name or ID (required when using a dataset name instead of ID)
`--verbose`, `-v`	Enable verbose logs

Examples:

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

`ax experiments list-runs`

List runs for an experiment (paginated table view). For bulk export of all runs, use ax experiments export instead.

ax experiments list-runs <name-or-id> [--dataset <name-or-id>] [--space <id>] [--limit <n>] [--output <fmt>] [--verbose]

Option	Description
`--dataset`	Dataset name or ID (required to resolve the experiment by name)
`--space`, `-s`	Space name or ID (required when using a dataset name instead of ID)
`--limit`, `-l`	Maximum number of runs to return (default: 15)
`--output`, `-o`	Output format (`table`, `json`, `csv`, `parquet`) or file path
`--verbose`, `-v`	Enable verbose logs

Examples:

ax experiments list-runs exp_abc123
ax experiments list-runs my-experiment --dataset my-eval-set --space my-space --limit 50

API reference

API clients

`ax experiments list`

`ax experiments create`

`ax experiments get`

`ax experiments run`

`ax experiments delete`

`ax experiments export`

`ax experiments annotate-runs`

`ax experiments list-runs`

​ax experiments list

​ax experiments create

​ax experiments get

​ax experiments run

​ax experiments delete

​ax experiments export

​ax experiments annotate-runs

​ax experiments list-runs

`ax experiments list`

`ax experiments create`

`ax experiments get`

`ax experiments run`

`ax experiments delete`

`ax experiments export`

`ax experiments annotate-runs`

`ax experiments list-runs`