arize-experiment

Arize Experiment Skill

SPACE — --space flags accept a space name (e.g., my-workspace) or a base64 space ID (e.g., U3BhY2U6...). Find yours with ax spaces list.

Concepts

• Experiment = a named evaluation run against a specific dataset version, containing one run per example
• Experiment Run = the result of processing one dataset example -- includes the model output, optional evaluations, and optional metadata
• Dataset = a versioned collection of examples; every experiment is tied to a dataset and a specific dataset version
• Evaluation = a named metric attached to a run (e.g., correctness, relevance), with optional label, score, and explanation

The typical flow: export a dataset → process each example → collect outputs and evaluations → create an experiment with the runs.

Prerequisites

Proceed directly with the task — run the ax command you need. Do NOT check versions, env vars, or profiles upfront.

If an ax command fails, troubleshoot based on the error:

• command not found or version error → see references/ax-setup.md
• 401 Unauthorized / missing API key → run ax profiles show to inspect the current profile. If the profile is missing or the API key is wrong, follow references/ax-profiles.md to create/update it. If the user doesn't have their key, direct them to https://app.arize.com/admin > API Keys
• Space unknown → run ax spaces list to pick by name, or ask the user
• Project unclear → ask the user, or run ax projects list -o json --limit 100 and present as selectable options
• Security: Never read .env files or search the filesystem for credentials. Use ax profiles for Arize credentials and ax ai-integrations for LLM provider keys. Never ask the user to paste secrets into chat. For missing credentials, see references/ax-profiles.md.
• CRITICAL — Never fabricate outputs: When running an experiment, you MUST call the real model API specified by the user for every dataset example. Never fabricate, simulate, or hardcode model outputs, latencies, or evaluation scores. If you cannot call the API (missing SDK, missing credentials, network error), stop and tell the user what is needed before proceeding.

List Experiments: ax experiments list

Browse experiments, optionally filtered by dataset. Output goes to stdout.

ax experiments list
ax experiments list --dataset DATASET_NAME --space SPACE --limit 20   # DATASET_NAME: name or ID (name preferred)
ax

Flags: see references/experiments-cli.md#list.

Get Experiment: ax experiments get

Quick metadata lookup -- returns experiment name, linked dataset/version, and timestamps.

Flags: see references/experiments-cli.md#get.

Response fields

Export Experiment: ax experiments export

Download all runs to a file. By default uses the REST API; pass --all to use Arrow Flight for bulk transfer.

Flags: see references/experiments-cli.md#export.

REST vs Flight (--all)

• REST (default): Lower friction -- no Arrow/Flight dependency, standard HTTPS ports, works through any corporate proxy or firewall. Limited to 500 runs per page.
• Flight (--all): Required for experiments with more than 500 runs. Uses gRPC+TLS on a separate host/port which some corporate networks may block. The active ax profile supplies the regional endpoint; see profile setup.

Agent auto-escalation rule: If a REST export returns exactly 500 runs, the result is likely truncated. Re-run with --all to get the full dataset.

Output is a JSON array of run objects:

Create Experiment: ax experiments create

Create a new experiment with runs from a data file.

Flags: see references/experiments-cli.md#create. --dataset is optional — omit it to create a standalone experiment with no linked dataset (then --space is required instead).

Passing data via stdin

Use --file - to pipe data directly — no temp file needed:

Required columns in the runs file

Additional columns are passed through as additionalProperties on the run.

example_id must be the Arize row id — the top-level id field on each exported dataset example (ex["id"]). Do not use a value nested inside the example's input fields or additional_properties; a wrong value fails silently or attaches the run to the wrong example. Export the dataset and inspect the top-level id field before creating runs.

⚠️ Inline evaluations in the create file do NOT attach as scores. create only reads example_id and output; every other column — including an evaluations object — is stored as a passthrough additional field, not as an experiment evaluation, and will not appear as a score in the UI. This fails silently (no error). To attach scores/labels, create the experiment first, then run ax experiments annotate-runs. The evaluations object in the schemas below is the export (read) shape returned once annotations exist — it is not an input to create.

Run a Task Locally: ax experiments run

Unlike create (needs a pre-computed outputs file), run loads a Python task function, executes it against every dataset row, and uploads the results as an experiment.

task.py must define a top-level task(dataset_row) function returning a JSON-serializable value:

--dry-run tests against the first 10 examples without uploading, to validate the task before a full run. Flags: see references/experiments-cli.md#run.

Choose the run path based on where the logic lives. Use ax experiments run when there's a local Python task to execute — it runs task.py on this machine and uploads the results; no AI integration is required. Use ax tasks create-run-experiment when the run should be hosted and recurring — it registers a platform-side run_experiment task that Arize executes on a schedule or on demand, driven by a JSON --run-configuration (model + messages + AI integration) instead of local code. Default to ax experiments run for local/ad-hoc runs and custom logic; use the task path for recurring, hosted runs — see the arize-evaluator skill for that route.

List Runs: ax experiments list-runs

Paginated terminal view of an experiment's runs (vs. export, which downloads them to a file).

Flags: see references/experiments-cli.md#list-runs.

Delete Experiment: ax experiments delete

Flags: see references/experiments-cli.md#delete.

Annotate Runs: ax experiments annotate-runs

This is the required step to attach evaluation scores/labels to an experiment and make them show up in the UI. Evaluations cannot be attached through create; see the warning under Create Experiment. You write them here, after the experiment exists. Upsert semantics — resubmitting the same annotation name for the same run overwrites the previous value. Up to 1000 runs per request; unmatched record IDs are silently ignored.

Annotation file schema

A JSON array; each item annotates one run:

record_id keys on the run id, which only exists after create. So the order is always: create → export (to read each run's id) → build annotations → annotate-runs.

Flags: see references/experiments-cli.md#annotate-runs.

Experiment Run Schema

Each run corresponds to one dataset example. On create, only example_id and output are consumed — evaluations shown here is the shape export returns after you attach scores via annotate-runs; it is not an input to create.

Evaluation fields

At least one of label, score, or explanation should be present per evaluation.

Workflows

Run an experiment against a dataset

1. Find or create a dataset:

   ax datasets list --space SPACE
   ax datasets export DATASET_NAME --space SPACE --stdout | jq 'length'

2. Export the dataset examples:

   ax datasets export DATASET_NAME --space SPACE

3. Call the real model API for each example and collect outputs. Use ax datasets export --stdout to pipe examples directly into an inference script:

   ax datasets export DATASET_NAME --space SPACE --stdout | python3 infer.py > runs.json

   Write infer.py to read examples from stdin, call the target model, and write runs JSON to stdout. Start from the template at references/inference-template.py — copy it, inspect the exported dataset JSON to confirm the input field name, then uncomment the provider block the user wants.

   Before running: install the SDK, set the API key env var. If the API isn't reachable, stop and tell the user.

4. Verify the runs file:

   python3 -c "import json; runs=json.load(open('runs.json')); print(f'{len(runs)} runs'); print(json.dumps(runs[0], indent=2))"

   Each run must have example_id (the dataset row's top-level id) and output. metadata is optional. Do not put evaluations here — create ignores them; scores are attached in steps 7–9 below.

5. Create the experiment:

   ax experiments create --name "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE --file runs.json

6. Verify: ax experiments get "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE

   Attach evaluation scores (required for scores to show in the UI). Evaluations do not come from the create file — you attach them with annotate-runs, which keys on each run's id (assigned at create time), so you must export first to learn those IDs.

7. Export the experiment to structured data so you can read each run's id alongside its example_id. Confirm that the exported run records include both fields.

8. Build the annotation file with structured JSON handling, keyed by record_id (the run id). Score/label each run via an LLM-as-judge, a code check, or human review; never fabricate scores. Emit this shape:

   [
     {
       "record_id": "RUN_ID_FROM_EXPERIMENT_EXPORT",
       "values": [
         { "name": "correctness", "score": 1.0, "label": "correct" }
       ]
     }
   ]

9. Attach the scores with ax experiments annotate-runs ... --file annotations.json, then export or inspect the experiment to confirm the evaluations are attached. The scores now render in the experiment view in the Arize UI.

Compare two experiments

1. Export both experiments:

   ax experiments export "experiment-a" --dataset DATASET_NAME --space SPACE --stdout > a.json
   ax experiments export "experiment-b" --dataset DATASET_NAME --space SPACE --stdout > b.json
2. Average correctness score (swap a.json for b.json to check the other experiment):

   jq '[.[] | .evaluations.correctness.score] | add / length' a.json
3. Find examples where results differ:

   jq -s '.[0] as $a | .[1][] | . as $run | {example_id: $run.example_id, b_score: $run.evaluations.correctness.score, a_score: ($a[] | select(.example_id == $run.example_id) | .evaluations.correctness.score)}' a.json b.json
4. Score distribution per evaluator (pass/fail/partial counts; swap files for the other experiment):

   jq '[.[] | .evaluations.correctness.label] | group_by(.) | map({label: .[0], count: length})' a.json
5. Find regressions (examples that passed in A but fail in B):

   jq -s '[.[0][] | select(.evaluations.correctness.label == "correct")] as $passed_a | [.[1][] | select(.evaluations.correctness.label != "correct") | select(.example_id as $id | $passed_a | any(.example_id == $id))]' a.json b.json

Statistical significance note: reliable with ≥ 30 examples per evaluator; with fewer, treat the delta as directional only — a 5% difference on n=10 may be noise. Report sample size alongside scores: jq 'length' a.json.

Download experiment results for analysis

1. ax experiments list --dataset DATASET_NAME --space SPACE -- find experiments
2. ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE -- download to file
3. Parse: jq '.[] | {example_id, score: .evaluations.correctness.score}' experiment_*/runs.json

Pipe export to other tools

# Count runs
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq 'length'
 
# Extract all outputs
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '.[].output'
 
# Get runs with low scores
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '[.[] | select(.evaluations.correctness.score < 0.5)]'
 
# Convert to CSV
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq -r '.[] | [.example_id, .output, .evaluations.correctness.score] | @csv'

Related Skills

• arize-dataset: Create or export the dataset this experiment runs against → use arize-dataset first
• arize-prompts: Store and version the prompt template in Prompt Hub (ax prompts) before or after experiments
• arize-prompt-optimization: Use experiment results to improve prompts → next step is arize-prompt-optimization
• arize-trace: Inspect individual span traces for failing experiment runs → use arize-trace
• arize-link: Generate clickable UI links to traces from experiment runs → use arize-link

Troubleshooting

Save Credentials for Future Use

See references/ax-profiles.md § Save Credentials for Future Use.*