ax run
Inspect and manage runs created by ax experiment run.
| Command | Use |
|---|---|
run list | List local and platform runs. |
run view | View a run request roll-up or one run in detail. |
run watch | Poll a run request until it finishes. |
run query | SQL scoped to one run. |
run rerun | Rerun failed variants, or re-run tests only. |
run cancel | Cancel queued or in-flight work. |
run download | Download a run's Parquet tables. |
run upload | Upload a local run to the platform. |
run clean | Remove orphaned local sandbox containers. |
Two id shapes appear below: a run request id covers one ax experiment run
submission, and a composite run id (<variant_id>::<hash>) names one run
inside it. Platform-backed commands also accept --org <org-id> and --json;
they are not repeated in the tables. Arguments marked required must be
supplied; everything else is optional, and flags combine freely unless a row
says otherwise.
run list
List runs, one row per run, grouped by status and newest first.
ax run list| Argument / flag | What it does |
|---|---|
--experiment <id-name-or-url> | Scope to one experiment by id, exact display name, or details-page URL. Omit to list runs across the org. |
--group-by <dimension> | Group rows by status (default), experiment, variant, agent, product, environment, or prompt. |
--agent / --model / --variant / --product / --environment / --prompt | Dimension filters (repeatable, comma-separated). |
--status <status> | Filter by queued, waiting-for-ci, running, completed, failed, canceled. Default shows everything except canceled. |
--triggered-by <user-id> | Runs triggered by these users (platform runs only). |
--since <RFC3339> | Status last updated at or after this time. |
--experiment-version <v> | latest (default) or a version fingerprint (platform runs only). |
--scope <scope> | local (.axp/runs/, no network), remote, or both (default). |
--limit <n> | Max remote runs (default 50, platform cap 500). |
--output-root <dir> | Where to read local runs from (default .). |
Examples:
# Failed runs for one experiment
ax run list --experiment my-experiment --status failed
# Local runs only, grouped by variant
ax run list --scope local --group-by variantrun view
View a run request roll-up, or one run in detail with its tests.
ax run view <RUN_REQUEST_ID | RUN_ID>| Argument / flag | What it does |
|---|---|
<RUN_REQUEST_ID | RUN_ID> | Required. Request id for the roll-up, or composite run id for one run. |
--tests | Per-test summary table (name, status, exit, duration). Not with --test. |
--test <name> | Stdout/stderr detail for one test. Composite run ids only. |
--scope <scope> | Resolve composite ids from local, remote, or both (default). |
--web | Open the run page in a browser. |
--output-root <dir> | Where to read local runs from (default .). |
Run status and test outcome are separate signals: a run whose agent finished
but whose tests failed is still completed (with a non-green tests line);
only infrastructure failures are failed. For request roll-ups the command
exits non-zero when any run ended unsuccessfully (setup failure, timeout,
cancel); test failures alone do not change the exit code.
Examples:
# Roll-up for a whole submission
ax run view 01KSDQ...
# One run's failing test, with output
ax run view 'claude::p0::abc123' --test report-existsrun watch
Poll a run request until it reaches a terminal status.
ax run watch <RUN_REQUEST_ID>run query
Run read-only SQL scoped to one run: against uploaded platform data, or a
local run with --local.
ax run query <RUN_ID> --sql "SELECT * FROM tests"| Argument / flag | What it does |
|---|---|
<RUN_ID> | Required. Composite run id, as printed by ax run list. |
--sql <SQL|@file|-> | Required. Inline SQL, @file.sql, or - for stdin. |
--local | Query the local run with DuckDB instead of platform ClickHouse. |
--limit <n> | Max rows for platform queries (default 100, server cap 1000). |
--table | Render an ASCII table instead of NDJSON. |
--dry-run | Validate without executing. |
--save <heading> | Save the query as an insight. --slug, --description, --label, and --force only apply together with it. |
--output-root <dir> | Where to read local runs from. Only with --local. |
Examples:
# Failing tests for one run
ax run query 'claude::p0::abc123' --sql \
"SELECT test_name, exit_code FROM tests WHERE exit_code != 0" --table
# Same run, offline
ax run query 'claude::p0::abc123' --sql "SELECT * FROM runs" --localrun rerun
Rerun failed or canceled variants from a prior platform request, or re-run
tests only against completed runs with --tests (see Tests).
ax run rerun <RUN_REQUEST_ID>
ax run rerun <RUN_ID> --tests --experiment experiment.yaml| Argument / flag | What it does |
|---|---|
<RUN_OR_REQUEST_ID>... | Required. Request id(s) to rerun, or run id(s) to retest with --tests. |
--tests | Re-run tests only; the agent is not driven again. |
--experiment <path> | Use this edited YAML instead of the latest registered version. |
--variant <id> | Limit which variants are retested (exact ids, repeatable). |
--flag <name> | Override inherited run-request flags. Not with --tests. |
--local | Retest a local .axp/runs group. Only with --tests. |
--run <id> / --env <NAME[=VALUE]> / --env-file <path> / --output-root <dir> | Local retest targeting and secrets. Only with --tests --local. |
Remote test-only reruns execute against each run's captured sandbox snapshot; if the snapshot was garbage-collected or never captured, the submit is rejected and you should create new runs instead.
run cancel
Cancel all jobs in a run request, or selected runs within it.
ax run cancel <RUN_REQUEST_ID>| Argument / flag | What it does |
|---|---|
<RUN_REQUEST_ID> | Required. Request id, as printed by ax experiment run. |
--run <id,...> | Cancel only these run ids; default cancels all. |
run download
Download a run's Parquet tables to .axp/downloads/<id>/ for local analysis.
ax run download [RUN_ID]| Argument / flag | What it does |
|---|---|
[RUN_ID] | Request or composite run id. Omit to use the most recent local group. |
--force | Overwrite an existing download directory. |
run upload
Upload a local run to the platform so it appears alongside platform runs.
ax run upload [RUN_ID]| Argument / flag | What it does |
|---|---|
[RUN_ID] | Run id. Omit to use the most recent completed local group. |
--force | Retry an existing upload of the same run. |
run clean
List orphaned local sandbox containers, and remove them with --yes.
ax run clean [--yes]| Argument / flag | What it does |
|---|---|
--yes | Actually remove. Without it, only lists the orphans. |