Datasets

REST API methods for interacting with Phoenix datasets

List datasets

get

Query parameters

cursorany ofOptional

Cursor for pagination

stringOptional

or

nullOptional

nameany ofOptional

An optional dataset name to filter by

stringOptional

or

nullOptional

limitintegerOptional

The max number of datasets to return at a time.

Default: 10

Responses

200

Successful Response

application/json

403

Forbidden

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/datasets HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "created_at": "2025-05-10T06:48:59.370Z",
      "updated_at": "2025-05-10T06:48:59.370Z"
    }
  ],
  "next_cursor": "text"
}

Get dataset by ID

get

Path parameters

idstringRequired

The ID of the dataset

Responses

200

Successful Response

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /v1/datasets/{id} HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "id": "text",
    "name": "text",
    "description": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "created_at": "2025-05-10T06:48:59.370Z",
    "updated_at": "2025-05-10T06:48:59.370Z",
    "example_count": 1
  }
}

Delete dataset by ID

delete

Path parameters

idstringRequired

The ID of the dataset to delete.

Responses

204

Successful Response

403

Forbidden

text/plain

404

Dataset not found

text/plain

422

Invalid dataset ID

text/plain

delete

HTTPcURLJavaScriptPython

DELETE /v1/datasets/{id} HTTP/1.1
Host: 
Accept: */*

No content

List dataset versions

get

Path parameters

idstringRequired

The ID of the dataset

Query parameters

cursorany ofOptional

Cursor for pagination

stringOptional

or

nullOptional

limitintegerOptional

The max number of dataset versions to return at a time

Default: 10

Responses

200

Successful Response

application/json

403

Forbidden

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/datasets/{id}/versions HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "version_id": "text",
      "description": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "created_at": "2025-05-10T06:48:59.370Z"
    }
  ],
  "next_cursor": "text"
}

Upload dataset from JSON, CSV, or PyArrow

post

Query parameters

syncbooleanOptional

If true, fulfill request synchronously and return JSON containing dataset_id.

Default: false

Body

application/jsonmultipart/form-data

actionstring · enumOptionalPossible values:

namestringRequired

descriptionstringOptional

inputsobject[]Required

outputsobject[]Optional

metadataobject[]Optional

Responses

200

Successful Response

application/json

Responseany of

or

nullOptional

403

Forbidden

text/plain

409

Dataset of the same name already exists

text/plain

422

Invalid request body

text/plain

post

HTTPcURLJavaScriptPython

POST /v1/datasets/upload HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "action": "create",
  "name": "text",
  "description": "text",
  "inputs": [
    {}
  ],
  "outputs": [
    {}
  ],
  "metadata": [
    {}
  ]
}

application/jsonmultipart/form-data

{
  "data": {
    "dataset_id": "text"
  }
}

Get examples from a dataset

get

Path parameters

idstringRequired

The ID of the dataset

Query parameters

version_idany ofOptional

The ID of the dataset version (if omitted, returns data from the latest version)

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /v1/datasets/{id}/examples HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "dataset_id": "text",
    "version_id": "text",
    "examples": [
      {
        "id": "text",
        "input": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "output": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "metadata": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "updated_at": "2025-05-10T06:48:59.370Z"
      }
    ]
  }
}

Download dataset examples as CSV file

get

Path parameters

idstringRequired

The ID of the dataset

Query parameters

version_idany ofOptional

The ID of the dataset version (if omitted, returns data from the latest version)

stringOptional

or

nullOptional

Responses

200

Successful Response

text/csv

Responsestring

403

Forbidden

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/datasets/{id}/csv HTTP/1.1
Host: 
Accept: */*

text

Download dataset examples as OpenAI fine-tuning JSONL file

get

Path parameters

idstringRequired

The ID of the dataset

Query parameters

version_idany ofOptional

The ID of the dataset version (if omitted, returns data from the latest version)

stringOptional

or

nullOptional

Responses

200

Successful Response

text/plain

Responsestring

403

Forbidden

text/plain

422

Invalid dataset or version ID

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/datasets/{id}/jsonl/openai_ft HTTP/1.1
Host: 
Accept: */*

text

Download dataset examples as OpenAI evals JSONL file

get

Path parameters

idstringRequired

The ID of the dataset

Query parameters

version_idany ofOptional

The ID of the dataset version (if omitted, returns data from the latest version)

stringOptional

or

nullOptional

Responses

200

Successful Response

text/plain

Responsestring

403

Forbidden

text/plain

422

Invalid dataset or version ID

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/datasets/{id}/jsonl/openai_evals HTTP/1.1
Host: 
Accept: */*

text