ax datasets list
ax datasets list --space SPACE --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

ax datasets get NAME_OR_ID
ax datasets get NAME_OR_ID -o json
ax datasets get NAME_OR_ID --space SPACE # required when using dataset name instead of ID

ax datasets export NAME_OR_ID
# -> dataset_abc123_20260305_141500/examples.json

ax datasets export NAME_OR_ID --all
ax datasets export NAME_OR_ID --version-id VERSION_ID
ax datasets export NAME_OR_ID --output-dir ./data
ax datasets export NAME_OR_ID --stdout
ax datasets export NAME_OR_ID --stdout | jq '.[0]'
ax datasets export NAME_OR_ID --space SPACE # required when using dataset name instead of ID

# Get the server-reported count from dataset metadata
ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions[-1] | {version: .id, examples: .example_count}'

# Compare to what was exported
jq 'length' dataset_*/examples.json

# If counts differ, re-export with --all

[
 {
 "id": "ex_001",
 "created_at": "2026-01-15T10:00:00Z",
 "updated_at": "2026-01-15T10:00:00Z",
 "question": "What is 2+2?",
 "answer": "4",
 "topic": "math"
 }
]

ax datasets create --name "My Dataset" --space SPACE --file data.csv
ax datasets create --name "My Dataset" --space SPACE --file data.json
ax datasets create --name "My Dataset" --space SPACE --file data.jsonl
ax datasets create --name "My Dataset" --space SPACE --file data.parquet

echo '[{"question": "What is 2+2?", "answer": "4"}]' | ax datasets create --name "my-dataset" --space SPACE --file -

# Or with a heredoc
ax datasets create --name "my-dataset" --space SPACE --file - To add rows to an existing dataset, use `ax datasets append --json '[...]'` instead — no file needed.

### Supported file formats

 Format Extension Notes 
 CSV `.csv` Column headers become field names 
 JSON `.json` Array of objects 
 JSON Lines `.jsonl` One object per line (NOT a JSON array) 
 Parquet `.parquet` Column names become field names; preserves types 
 

 **Format gotchas:**

 

- **CSV**: Loses type information — dates become strings, `null` becomes empty string. Use JSON/Parquet to preserve types. 

- **JSONL**: Each line is a separate JSON object. A JSON array (`[{...}, {...}]`) in a `.jsonl` file will fail — use `.json` extension instead. 

- **Parquet**: Preserves column types. Requires `pandas`/`pyarrow` to read locally: `pd.read_parquet("examples.parquet")`.

## Append Examples: `ax datasets append`

Add examples to an existing dataset. Two input modes -- use whichever fits.

### Inline JSON (agent-friendly)

 Generate the payload directly -- no temp files needed:

### From a file

### To a specific version

### Flags

 Flag Type Required Description 
 `NAME_OR_ID` string yes Dataset name or ID (positional); add `--space` when using name 
 `--space` string no Space name or ID (required if using dataset name instead of ID) 
 `--json` string mutex JSON array of example objects 
 `--file, -f` path mutex Data file (CSV, JSON, JSONL, Parquet) 
 `--version-id` string no Append to a specific version (default: latest) 
 `-o, --output` string no Output format for the returned dataset metadata 
 `-p, --profile` string no Configuration profile 
 

 Exactly one of `--json` or `--file` is required.

### Validation

 

- Each example must be a JSON object with at least one user-defined field 

- Maximum 100,000 examples per request 

 **Schema validation before append:** If the dataset already has examples, inspect its schema before appending to avoid silent field mismatches:

 Fields are free-form: extra fields in new examples are added, and missing fields become null. However, typos in field names (e.g., `queston` vs `question`) create new columns silently -- verify spelling before appending.

## Delete Dataset: `ax datasets delete`

### Flags

 Flag Type Default Description 
 `NAME_OR_ID` string required Dataset name or ID (positional) 
 `--space` string none Space name or ID (required if using dataset name instead of ID) 
 `--force, -f` bool false Skip confirmation prompt 
 `-p, --profile` string default Configuration profile

## Workflows

### Find a dataset by name

 All dataset commands accept a name or ID directly. You can pass a dataset name as the positional argument (add `--space SPACE` when not using an ID):

### Create a dataset from file for evaluation

 

- Prepare a CSV/JSON/Parquet file with your evaluation columns (e.g., `input`, `expected_output`)
 

- If generating data inline, pipe it via stdin using `--file -` (see the Create Dataset section) 

 

- `ax datasets create --name "eval-set-v1" --space SPACE --file eval_data.csv` 

- Verify: `ax datasets get DATASET_NAME --space SPACE` 

- Use the dataset name to run experiments 

### Add examples to an existing dataset

### Download dataset for offline analysis

 

- `ax datasets list --space SPACE` -- find the dataset name 

- `ax datasets export DATASET_NAME --space SPACE` -- download to file 

- Parse the JSON: `jq '.[] | .question' dataset_*/examples.json` 

### Export a specific version

### Iterate on a dataset

 

- Export current version: `ax datasets export DATASET_NAME --space SPACE` 

- Modify the examples locally 

- Append new rows: `ax datasets append DATASET_NAME --space SPACE --file new_rows.csv` 

- Or create a fresh version: `ax datasets create --name "eval-set-v2" --space SPACE --file updated_data.json` 

### Pipe export to other tools

## Dataset Example Schema

Examples are free-form JSON objects. There is no fixed schema -- columns are whatever fields you provide. System-managed fields are added by the server:

 Field Type Managed by Notes 
 `id` string server Auto-generated UUID. Required on update, forbidden on create/append 
 `created_at` datetime server Immutable creation timestamp 
 `updated_at` datetime server Auto-updated on modification 
 (any user field) any JSON type user String, number, boolean, null, nested object, array

## Related Skills

- **arize-trace**: Export production spans to understand what data to put in datasets → use `arize-trace` 

- **arize-experiment**: Run evaluations against this dataset → next step is `arize-experiment` 

- **arize-prompt-optimization**: Use dataset + experiment results to improve prompts → use `arize-prompt-optimization`

## Save Credentials for Future Use

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