TypeScript APIPython APICommunityGitHubPhoenix Cloud
Edit

Experiments

REST API methods for interacting with Phoenix experiments

List experiments by dataset

get
Path parameters
dataset_idstringRequired
Responses
200

Experiments retrieved successfully

application/json
get
GET /v1/datasets/{dataset_id}/experiments HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "id": "text",
      "dataset_id": "text",
      "dataset_version_id": "text",
      "repetitions": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "project_name": "text",
      "created_at": "2025-09-26T23:44:05.224Z",
      "updated_at": "2025-09-26T23:44:05.224Z"
    }
  ]
}

Create experiment on a dataset

post
Path parameters
dataset_idstringRequired
Body

Details of the experiment to be created

nameany ofOptional

Name of the experiment (if omitted, a random name will be generated)

stringOptional
or
nullOptional
descriptionany ofOptional

An optional description of the experiment

stringOptional
or
nullOptional
metadataany ofOptional

Metadata for the experiment

or
nullOptional
version_idany ofOptional

ID of the dataset version over which the experiment will be run (if omitted, the latest version will be used)

stringOptional
or
nullOptional
repetitionsintegerOptional

Number of times the experiment should be repeated for each example

Default: 1
Responses
200

Experiment retrieved successfully

application/json
post
POST /v1/datasets/{dataset_id}/experiments HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 122

{
  "name": "text",
  "description": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "version_id": "text",
  "repetitions": 1
}
{
  "data": {
    "id": "text",
    "dataset_id": "text",
    "dataset_version_id": "text",
    "repetitions": 1,
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "project_name": "text",
    "created_at": "2025-09-26T23:44:05.224Z",
    "updated_at": "2025-09-26T23:44:05.224Z"
  }
}

Get experiment by ID

get
Path parameters
experiment_idstringRequired
Responses
200

Experiment retrieved successfully

application/json
get
GET /v1/experiments/{experiment_id} HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "id": "text",
    "dataset_id": "text",
    "dataset_version_id": "text",
    "repetitions": 1,
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "project_name": "text",
    "created_at": "2025-09-26T23:44:05.224Z",
    "updated_at": "2025-09-26T23:44:05.224Z"
  }
}

Download experiment runs as a JSON file

get
Path parameters
experiment_idstringRequired
Responses
200

Successful Response

text/plain
Responsestring
get
GET /v1/experiments/{experiment_id}/json HTTP/1.1
Host: 
Accept: */*

text

Download experiment runs as a CSV file

get
Path parameters
experiment_idstringRequired
Responses
200

Successful Response

Responseany
get
GET /v1/experiments/{experiment_id}/csv HTTP/1.1
Host: 
Accept: */*

No content

List runs for an experiment

get

Retrieve a paginated list of runs for an experiment

Path parameters
experiment_idstringRequired
Query parameters
cursorany ofOptional

Cursor for pagination (base64-encoded experiment run ID)

stringOptional
or
nullOptional
limitany ofOptional

The max number of experiment runs to return at a time. If not specified, returns all results.

integerOptional
or
nullOptional
Responses
200

Experiment runs retrieved successfully

application/json
get
GET /v1/experiments/{experiment_id}/runs HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "dataset_example_id": "text",
      "output": null,
      "repetition_number": 1,
      "start_time": "2025-09-26T23:44:05.224Z",
      "end_time": "2025-09-26T23:44:05.224Z",
      "trace_id": "text",
      "error": "text",
      "id": "text",
      "experiment_id": "text"
    }
  ],
  "next_cursor": "text"
}

Create run for an experiment

post
Path parameters
experiment_idstringRequired
Body
dataset_example_idstringRequired

The ID of the dataset example used in the experiment run

outputanyRequired

The output of the experiment task

repetition_numberintegerRequired

The repetition number of the experiment run

start_timestring · date-timeRequired

The start time of the experiment run

end_timestring · date-timeRequired

The end time of the experiment run

trace_idany ofOptional

The ID of the corresponding trace (if one exists)

stringOptional
or
nullOptional
errorany ofOptional

Optional error message if the experiment run encountered an error

stringOptional
or
nullOptional
Responses
200

Experiment run created successfully

application/json
post
POST /v1/experiments/{experiment_id}/runs HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 176

{
  "dataset_example_id": "text",
  "output": null,
  "repetition_number": 1,
  "start_time": "2025-09-26T23:44:05.224Z",
  "end_time": "2025-09-26T23:44:05.224Z",
  "trace_id": "text",
  "error": "text"
}
{
  "data": {
    "id": "text"
  }
}

Create or update evaluation for an experiment run

post
Body
experiment_run_idstringRequired

The ID of the experiment run being evaluated

namestringRequired

The name of the evaluation

annotator_kindstring · enumRequired

The kind of annotator used for the evaluation

Possible values:
start_timestring · date-timeRequired

The start time of the evaluation in ISO format

end_timestring · date-timeRequired

The end time of the evaluation in ISO format

resultany ofOptional

The result of the evaluation. Either result or error must be provided.

or
nullOptional
errorany ofOptional

Error message if the evaluation encountered an error. Either result or error must be provided.

stringOptional
or
nullOptional
metadataany ofOptional

Metadata for the evaluation

or
nullOptional
trace_idany ofOptional

Optional trace ID for tracking

stringOptional
or
nullOptional
Responses
200

Successful Response

application/json
post
POST /v1/experiment_evaluations HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 283

{
  "experiment_run_id": "text",
  "name": "text",
  "annotator_kind": "LLM",
  "start_time": "2025-09-26T23:44:05.224Z",
  "end_time": "2025-09-26T23:44:05.224Z",
  "result": {
    "label": "text",
    "score": 1,
    "explanation": "text"
  },
  "error": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "trace_id": "text"
}
{
  "data": {
    "id": "text"
  }
}
PreviousDatasetsNextSpans

Last updated

Was this helpful?