---
title: "Add new examples to a dataset"
method: POST
path: "/v2/datasets/{dataset_id}/examples"
tags: ["Datasets"]
---

# Add new examples to a dataset

`POST /v2/datasets/{dataset_id}/examples`

Appends new examples to an existing dataset.

If the dataset version is not passed, the latest version is selected.
The inserted examples will be assigned autogenerated, unique IDs.

**Payload Requirements**
- Each item in `examples[]` may contain any user-defined fields.
- Do not include system-managed fields on input: `id`, `created_at`,
`updated_at`. Requests that contain these fields in any example will
be rejected.
- Each example must contain at least one property (i.e., `{}` is invalid).

**Valid example** (create)
```json
{
  "examples": [
    { "question": "What is 2+2?",
      "answer": "4",
      "topic": "math"
    }
  ]
}
```

**Invalid example** ('id' not allowed on create)
```json
{
  "examples": [
    {
      "id": "ex_1",
      "input": "Hello"
    }
  ]
}
```

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Path parameters

- `dataset_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Query parameters

- `dataset_version_id` string — A universally unique identifier (base64-encoded opaque string).

## Request body

- InsertDatasetExamplesRequest — Examples to append (insert) to a dataset version, with auto-generated IDs.
  - `examples` CreateDatasetExampleInput[], required — Array of examples to append to the dataset version

## Response `201`

Examples successfully added to the dataset.

- DatasetVersionWithExampleIds — A dataset with the IDs of examples that were inserted or updated. Includes the version the examples were written to and the list of affected example IDs.
  - `id` string, required — Unique identifier for the dataset
  - `name` string, required — Name of the dataset
  - `space_id` string, required — Unique identifier for the space this dataset belongs to
  - `created_at` string, date-time, required — Timestamp for when the dataset was created
  - `updated_at` string, date-time, required — Timestamp for the last update of the dataset
  - `dataset_version_id` string, required — Unique identifier for the dataset version the examples were written to
  - `example_ids` string[], required — IDs of the examples that were inserted or updated

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/1e87d8a4cf69/schema)