---
title: "Create an experiment"
method: POST
path: "/v2/experiments"
tags: ["Experiments"]
---

# Create an experiment

`POST /v2/experiments`

Create a new experiment. Empty experiments are not allowed.

An experiment belongs to a space and may optionally be associated with a
dataset.

Experiments are composed of "runs". Each experiment run (JSON object)
must include an `output` field containing the task's output. When the
experiment is associated with a dataset, each run must also include an
`example_id` referencing an example in that dataset.

Payload Requirements
- Provide exactly one of `dataset_id` or `space_id`.
- The `name` must be unique within the dataset it's associated with, or
  within the space when it isn't associated with a dataset.
- Provide at least one run in `experiment_runs`.
- Each run must include:
  - `output` -- model/task output for the run
  - `example_id` -- the ID of an existing example in the dataset,
  required only when the experiment is associated with a dataset
  - You may include any additional fields per run that can be used for
  analysis or filtering. For example: `model`, `latency_ms`,
  `temperature`, `prompt`, `tool_calls`, etc.

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Request body

- CreateExperimentRequest — Experiment creation parameters with an initial set of runs. An experiment belongs to a space and may optionally be associated with a dataset. Provide exactly one of: - `dataset_id` — associate the experiment with a dataset; it's created in that dataset's space, and its runs may reference the dataset's examples via `example_id`. - `space_id` — the space to create the experiment in, when it isn't associated with a dataset. Providing both, or neither, is a validation error.
  - `name` string, required — Name of the experiment
  - `dataset_id` string, nullable — ID of the dataset to associate the experiment with. Provide `space_id` instead when the experiment isn't associated with a dataset.
  - `space_id` string, nullable — ID of the space to create the experiment in. Provide instead of `dataset_id`.
  - `experiment_runs` ExperimentRunInput[], required — Array of experiment run data
    - `example_id` string, nullable — ID of the dataset example associated with this experiment run. Provided when the experiment is associated with a dataset; omitted otherwise.
    - `output` string, required — output of the task for the matching example

## Response `201`

An experiment object

- Experiment — Experiments combine a dataset (example inputs/expected outputs), a task (the function that produces model outputs), and one or more evaluators (code or LLM judges) to measure performance. Each run is stored independently so you can compare runs, track progress, and validate improvements over time. See the full definition on the Experiments page. Use an experiment to run tasks on a dataset, attach evaluators to score outputs, and compare runs to confirm improvements.
  - `id` string, required — Unique identifier for the experiment
  - `name` string, required — Name of the experiment
  - `space_id` string, required — Unique identifier for the space this experiment belongs to
  - `dataset_id` string, nullable — Unique identifier for the dataset associated with this experiment. Null if the experiment isn't associated with a dataset.
  - `dataset_version_id` string, nullable — Unique identifier for the dataset version associated with this experiment. Null if the experiment isn't associated with a dataset.
  - `created_at` string, date-time, required — Timestamp for when the experiment was created
  - `updated_at` string, date-time, required — Timestamp for the last update of the experiment
  - `experiment_traces_project_id` string — Unique identifier for the experiment traces project this experiment belongs to (if it exists)
  - `integration_id` string, nullable — Identifier (base64) of the agent integration that backs this experiment, as returned by the integrations API. Null for non-agent experiments (for example, SDK or Playground experiments).

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `409` — Resource conflict
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)