TypeScript APIPython APICommunityGitHubPhoenix Cloud

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-07-20T16:53:51.244Z",
      "updated_at": "2025-07-20T16:53:51.244Z"
    }
  ]
}

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-07-20T16:53:51.244Z",
    "updated_at": "2025-07-20T16:53:51.244Z"
  }
}

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-07-20T16:53:51.244Z",
    "updated_at": "2025-07-20T16:53:51.244Z"
  }
}

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
Path parameters
experiment_idstringRequired
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-07-20T16:53:51.244Z",
      "end_time": "2025-07-20T16:53:51.244Z",
      "trace_id": "text",
      "error": "text",
      "id": "text",
      "experiment_id": "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-07-20T16:53:51.244Z",
  "end_time": "2025-07-20T16:53:51.244Z",
  "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

errorany ofOptional

Optional error message if the evaluation encountered an error

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-07-20T16:53:51.244Z",
  "end_time": "2025-07-20T16:53:51.244Z",
  "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?