---
title: "Upload dataset from JSON, JSONL, CSV, or PyArrow"
method: POST
path: "/v1/datasets/upload"
tags: ["datasets"]
---

# Upload dataset from JSON, JSONL, CSV, or PyArrow

`POST /v1/datasets/upload`

## Query parameters

- `sync` boolean — If true, fulfill request synchronously and return JSON containing dataset_id.

## Request body

- object
  - `action` 'create' | 'append' | 'update'
  - `name` string, required
  - `description` string
  - `inputs` object[], required
  - `outputs` object[]
  - `metadata` object[]
  - `splits` union[] — Split per example: string, string array, or null
    - union
      - string
      - string[]
  - `span_ids` string[] — Span IDs to link examples back to spans
  - `example_ids` string[] — Optional example ID per example. If provided, it is used as the example's stable public ID.

## Response `200`

Successful Response

- UploadDatasetResponseBody
  - `data` UploadDatasetData, required
    - `dataset_id` string, required
    - `version_id` string, required
    - `num_created_examples` integer, required
    - `num_updated_examples` integer, required
    - `num_deleted_examples` integer, required

## Other responses

- `403` — Forbidden
- `409` — Dataset with the given name already exists (action=create).
- `422` — Invalid request body

## Changes

- **2026-04-29** `02361ac1935f` — 8 info
  - added the new optional request property `example_id_key` (media type: multipart/form-data)
  - added the new optional request property `example_ids` (media type: application/json)
  - added the new optional request property `split_key` (media type: multipart/form-data)
  - added the new `update` enum value to the request property `action` (media type: application/json)
  - …4 more
- **2026-04-29** `c81391216eb5` — 5 breaking, 3 warning
  - removed the enum value `update` of the request property `action` (media type: application/json)
  - removed the enum value `update` of the request property `action` (media type: multipart/form-data)
  - removed the required property `anyOf[subschema #1: UploadDatasetResponseBody]/data/num_created_examples` from the response with the `200` status
  - removed the required property `anyOf[subschema #1: UploadDatasetResponseBody]/data/num_deleted_examples` from the response with the `200` status
  - …4 more

[Change history](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/changes/v1/datasets/upload/post.md)

---

[API](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/f440cb6427a5/schema)