Sign in

v2

latestOpenAPI 3.0.3Apache-2.02026-08-07119359591.9 KB
Experiments

Create an experiment

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.</Note>

post/v2/experiments

Request body

namestring required

Name of the experiment

dataset_idstring nullable

ID of the dataset to associate the experiment with. Provide space_id instead when the experiment isn't associated with a dataset.

space_idstring nullable

ID of the space to create the experiment in. Provide instead of dataset_id.

Response

An experiment object

idstring required

Unique identifier for the experiment

namestring required

Name of the experiment

space_idstring required

Unique identifier for the space this experiment belongs to

dataset_idstring nullable

Unique identifier for the dataset associated with this experiment. Null if the experiment isn't associated with a dataset.

dataset_version_idstring nullable

Unique identifier for the dataset version associated with this experiment. Null if the experiment isn't associated with a dataset.

created_atstring date-time required

Timestamp for when the experiment was created

updated_atstring date-time required

Timestamp for the last update of the experiment

experiment_traces_project_idstring

Unique identifier for the experiment traces project this experiment belongs to (if it exists)

integration_idstring 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).