Datasets endpoints
GET /api/v1/projects/{project_id}/datasets
Section titled “GET /api/v1/projects/{project_id}/datasets”List datasets
Newest first. name returns the dataset of that exact name, if any.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
query | string or null | no | Exact name max length 100 |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no | max length 512 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_DatasetOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/datasets
Section titled “POST /api/v1/projects/{project_id}/datasets”Add a dataset
Store an empty dataset. 409 NAME_TAKEN.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
Request body (application/json, required): DatasetSpec
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: DatasetOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/datasets/{dataset_id}
Section titled “DELETE /api/v1/projects/{project_id}/datasets/{dataset_id}”Delete a dataset
Delete the dataset with its items. 409 DATASET_IN_USE while an experiment uses it.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/datasets/{dataset_id}
Section titled “GET /api/v1/projects/{project_id}/datasets/{dataset_id}”Get a dataset
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: DatasetOut |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/projects/{project_id}/datasets/{dataset_id}
Section titled “PATCH /api/v1/projects/{project_id}/datasets/{dataset_id}”Edit a dataset
Change the description; null clears it.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
Request body (application/json, required): DatasetPatch
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: DatasetOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/datasets/{dataset_id}/items
Section titled “GET /api/v1/projects/{project_id}/datasets/{dataset_id}/items”List a dataset’s items
By id, oldest first.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes | |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no | max length 512 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_ItemOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/datasets/{dataset_id}/items
Section titled “POST /api/v1/projects/{project_id}/datasets/{dataset_id}/items”Add items
Add up to 1 000 items. 422 DATASET_FULL past 10 000 items; nothing is stored then.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
Request body (application/json, required): ItemAddIn
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: ItemAddedOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/datasets/{dataset_id}/items/{item_id}
Section titled “DELETE /api/v1/projects/{project_id}/datasets/{dataset_id}/items/{item_id}”Delete an item
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes | |
item_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/projects/{project_id}/datasets/{dataset_id}/items/{item_id}
Section titled “PATCH /api/v1/projects/{project_id}/datasets/{dataset_id}/items/{item_id}”Edit an item
Change expected_output (null clears it) and metadata (replaced as a whole).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes | |
item_id |
path | string (uuid) | yes |
Request body (application/json, required): ItemPatch
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: ItemOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/datasets/{dataset_id}/items/from-traces
Section titled “POST /api/v1/projects/{project_id}/datasets/{dataset_id}/items/from-traces”Add items from traces
Copy one item from each of up to 200 traces: the span span_id, else the trace’s first
llm span. A trace that gives no item is listed in rejected with the reason (trace not found, no llm span, span not found, no payload stored, already in this dataset when
this dataset already holds that trace and span). An added trace that already has an item in
another dataset of the project is listed in also_in. The recorded output is only a starting
point for the expected output.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
Request body (application/json, required): ItemFromTracesIn
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: TraceAddedOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/datasets/{dataset_id}/items/upload
Section titled “POST /api/v1/projects/{project_id}/datasets/{dataset_id}/items/upload”Upload items
Add the items of a .jsonl or .csv file of UTF-8 text, at most 5 MB. A bad line is
listed in rejected with its line number and the rest is accepted. 415 UNSUPPORTED_FILE
for another extension or encoding, 413 PAYLOAD_TOO_LARGE past 5 MB.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
Request body (multipart/form-data, required): Body_upload_items_api_v1_projects__project_id__datasets__dataset_id__items_upload_post
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: UploadOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/datasets/{dataset_id}/lock
Section titled “POST /api/v1/projects/{project_id}/datasets/{dataset_id}/lock”Lock a dataset
Refuse item writes and the delete with 409 DATASET_LOCKED until the dataset is unlocked.
Reads, description edits and experiment runs still work. Locking a locked dataset keeps its
locked_at.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: DatasetOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/datasets/{dataset_id}/unlock
Section titled “POST /api/v1/projects/{project_id}/datasets/{dataset_id}/unlock”Unlock a dataset
Allow item writes and the delete again. Unlocking an unlocked dataset changes nothing.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
dataset_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: DatasetOut |
| 422 | Validation Error | application/json: HTTPValidationError |