---
title: "Update existing examples in a dataset"
method: PATCH
path: "/v2/datasets/{dataset_id}/examples"
tags: ["Datasets"]
---

# Update existing examples in a dataset

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

Updates existing dataset examples by matching their `id` field.

an example ID does not match any existing example in the dataset
version, it will be ignored. In other words, only examples with IDs
that already exist will be updated. To add new examples, use the
Insert Dataset Examples endpoint.

Adding columns that do not exist in the dataset schema is allowed, but
removing existing columns is not.

Optionally, the update can create a new version of the dataset. In
this case, the outcome of the update will be reflected only in the new
version, while the previous version remains unchanged. If a new
version is not created, the updates will be applied directly (in place)
to the specified version.

**Payload Requirements**
- Each item in `examples[]` may contain any user-defined fields.
- Each item in `examples[]` must include the `id` field to identify the
example to update.
- Do not include system-managed fields on input: `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": [
    {
      "id": "ex_001",
      "question": "What is 2+2?",
      "answer": "4",
      "topic": "math"
    }
  ]
}
```

**Invalid example** ('id' missing for update)
```json
{
  "examples": [
    {
      "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

- UpdateDatasetExamplesRequest — Examples to update by ID matching, optionally into a new version.
  - `examples` UpdateDatasetExampleInput[], required — Array of examples with 'id' field for matching and updating existing records
    - `id` string, required — System-assigned unique ID for the example
  - `new_version` string — Name for the new version. If provided (non-empty), creates a new version with that name. If omitted or empty, updates the existing version in-place.

## Response `200`

Examples successfully updated in 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
- `409` — Resource conflict
- `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)