---
title: "Create/update dataset items"
method: PUT
path: "/v1/private/datasets/items"
tags: ["Datasets"]
---

# Create/update dataset items

`PUT /v1/private/datasets/items`

Create/update dataset items based on dataset item id.
Each item's 'id' field is the stable identifier and upsert key.
Provide it to update an existing item, or omit it to create a new one.

Set 'copy_from_dataset_id' and 'copy_from_version_id' together to read carry-forward rows
from the supplied (dataset, version) pair instead of the destination's prior version. When
the fields are null, carry-forward rows are read from the destination's prior version.

## Request body

- DatasetItemBatchWrite
  - `dataset_name` string — If null, dataset_id must be provided
  - `dataset_id` string, uuid — If null, dataset_name must be provided
  - `project_name` string — Optional. Associates the batch with a project by name. Ignored if project_id is provided.
  - `project_id` string, uuid — Optional. Associates the batch with a project by ID. Takes precedence over project_name.
  - `items` DatasetItemWrite[], required
    - `id` string, uuid — Stable item identifier. On write, used as the upsert key. If omitted, a new ID is generated. Remains the same across dataset versions
    - `trace_id` string, uuid
    - `span_id` string, uuid
    - `source` 'manual' | 'trace' | 'span' | 'sdk', required
    - `data` JsonNode, required
    - `description` string
    - `tags` string[]
    - `evaluators` EvaluatorItemWrite[]
      - `name` string, required
      - `type` 'llm_judge' | 'code_metric', required
      - `config` JsonNodeWrite, required
    - `execution_policy` ExecutionPolicyWrite
      - `runs_per_item` integer
      - `pass_threshold` integer
  - `batch_group_id` string, uuid — Optional batch group ID to group multiple batches into a single dataset version. If null, mutates the latest version instead of creating a new one.
  - `copy_from_dataset_id` string, uuid — Optional. Dataset to read carry-forward rows from when materializing the new version. Required together with copy_from_version_id. When null, carry-forward rows are read from the destination dataset's prior version.
  - `copy_from_version_id` string, uuid — Optional. Version within copy_from_dataset_id to read carry-forward rows from. Required together with copy_from_dataset_id.

## Response `204`

No content

---

[API](https://skmtc.net/comet-ml/apis/opik-rest-api.md) · [All operations](https://skmtc.net/comet-ml/apis/opik-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/comet-ml/opik-rest-api/revisions/4ed2fbc97cc3/schema)