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

> Track and evaluate changes to prompts, models, and retrieval strategies using the Arize TypeScript SDK.

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

## List Experiments

```typescript theme={null}
import { listExperiments } from "@arizeai/ax-client";

// By dataset ID
const { data: experiments, pagination } = await listExperiments({
  dataset: "your_dataset_id",
  limit: 10,
});

// By dataset name (requires space)
const result = await listExperiments({
  dataset: "my-dataset",
  space: "my-space",
});
console.log(result.data);
```

## Create an Experiment

```typescript theme={null}
import { createExperiment } from "@arizeai/ax-client";

// Using dataset ID
const experiment = await createExperiment({
  experimentName: "your_experiment",
  dataset: "your_dataset_id",
  experimentRuns: [{ exampleId: "your_example_id", output: "output" }],
});

// Using dataset name (requires space)
const experiment = await createExperiment({
  experimentName: "your_experiment",
  dataset: "my-dataset",
  space: "my-space",
  experimentRuns: [{ exampleId: "your_example_id", output: "output" }],
});
```

## Get an Experiment

```typescript theme={null}
import { getExperiment } from "@arizeai/ax-client";

// By experiment ID
const experiment = await getExperiment({ experiment: "your_experiment_id" });

// By experiment name (requires dataset; space is required when dataset is a name)
const experiment = await getExperiment({
  experiment: "my-experiment",
  dataset: "my-dataset",
  space: "my-space",
});
```

## Delete an Experiment

```typescript theme={null}
import { deleteExperiment } from "@arizeai/ax-client";

// By experiment ID
await deleteExperiment({ experiment: "your_experiment_id" });

// By experiment name (requires dataset; space is required when dataset is a name)
await deleteExperiment({
  experiment: "my-experiment",
  dataset: "my-dataset",
  space: "my-space",
});
```

## List Experiment Runs

```typescript theme={null}
import { listExperimentRuns } from "@arizeai/ax-client";

const experimentRuns = await listExperimentRuns({
  experiment: "your_experiment_id",
  limit: 10,
});
// Or resolve by experiment name:
const experimentRuns2 = await listExperimentRuns({
  experiment: "my-experiment",
  dataset: "my-dataset",  // optional, used to resolve experiment by name
  space: "my-space",      // optional, used to resolve dataset by name
});
```

## Annotate Experiment Runs

Write human annotations to a batch of runs in an experiment. Annotations are upserted by annotation config name for each run; submitting the same name for the same run overwrites the previous value. Up to 1000 runs may be annotated per request.

```typescript theme={null}
import { annotateExperimentRuns } from "@arizeai/ax-client";

await annotateExperimentRuns({
  experiment: "my-experiment",  // experiment name or ID
  dataset: "my-dataset",        // optional, used to resolve experiment by name
  space: "my-space",            // optional, used to resolve dataset by name
  annotations: [
    {
      recordId: "your_run_id",
      values: [
        { name: "accuracy", label: "correct", score: 1.0 },
        { name: "notes", text: "Well-structured output" },
      ],
    },
  ],
});
```