Documentation | Dataset Items

Dataset Items

DatasetItemsResource

Methods

client.dataset_items.batch_create() ->

post/v5/dataset-items/batch

Add one or more items in a single batch to a dataset that already exists.

Use this to append items to an existing dataset; to create a dataset together with its initial items in one call, use POST /v5/datasets instead (this endpoint does not create datasets). Items are only ever added in a batch — there is no single-item create endpoint. The target dataset is identified by the required dataset_id in the request body, and each entry in data (at least one is required) becomes one item, optionally paired with the files entry at the same list index — when files is supplied it must be the same length as data. Each referenced file must exist and be a supported media format, and item keys may not collide with reserved dataset- or evaluation-item field names. The target dataset must not be archived. The batch is applied as a new dataset version snapshot rather than mutating existing versions, and the created items are returned.

client.dataset_items.retrieve(, ) ->

DatasetItem

get/v5/dataset-items/{dataset_item_id}

Retrieve a single dataset item by its identifier.

The lookup is scoped to the caller's account. By default the current (latest) version of the item is returned; passing version returns the item as it existed at that dataset version, which allows reading an item that was later updated or soft-deleted.

client.dataset_items.archive() ->

DatasetItemArchiveResponse

delete/v5/dataset-items/{dataset_item_id}

Soft-delete a dataset item by marking it as removed in the current dataset version.

The database row is not removed; instead the item's end version is set to the current dataset version so it no longer appears at the latest version while remaining retrievable at earlier versions, and a new dataset version snapshot is created to record the removal. An item that is already archived or already deleted cannot be deleted again. The response echoes the item id with deleted set to true.

client.dataset_items.update(, ) ->

DatasetItem

patch/v5/dataset-items/{dataset_item_id}

Update the data payload and optional file associations of a dataset item.

The request replaces the item's data in full and, if provided, its file associations; there is no partial-field merge. Data keys may not collide with reserved dataset- or evaluation-item field names, and any referenced files must exist and be a supported media format. Items that are archived or soft-deleted cannot be updated. The update is applied as a new dataset version rather than overwriting the previous record, so prior versions remain retrievable.

Parameters

dataset_item_id: str

data: Dict[str,

object

]

Updated dataset item data

files: Optional[Dict[str, str]]

Files to be associated to the dataset

Returns

DatasetItem

id: str

The unique identifier of the entity.

content_hash: str

created_at:

datetime

(format: date-time)

The date and time when the entity was created in ISO format.

created_by:

Identity

The identity that created the entity.

data: Dict[str,

object

]

updated_at:

datetime

(format: date-time)

The date and time when the entity was last updated in ISO format.

archived_at: Optional[datetime]

(format: date-time)

The date and time when the entity was archived in ISO format.

dataset_id: Optional[str]

files: Optional[Dict[str, str]]

object: Optional[Literal["dataset.item"]]

(default: "dataset.item")

Request example

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
dataset_item = client.dataset_items.update(
    dataset_item_id="dataset_item_id",
    data={
        "foo": "bar"
    },
)
print(dataset_item.id)

200Example

{
  "id": "id",
  "content_hash": "content_hash",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "data": {
    "foo": "bar"
  },
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "dataset_id": "dataset_id",
  "files": {
    "foo": "string"
  },
  "object": "dataset.item"
}

client.dataset_items.list() -> SyncCursorPage[

DatasetItem

]

get/v5/dataset-items

List dataset items belonging to the caller's account, paginated.

dataset_id is optional: when omitted, items across all of the account's datasets are returned; when provided, results are restricted to that dataset. A specific version may be requested only together with a dataset_id — passing version without dataset_id is rejected. By default only current items at the latest version are listed (soft-deleted items are excluded); archived items are excluded unless include_archived is true.

Domain types

class DatasetItem: ...

class DatasetItemArchiveResponse: ...

class DatasetItemBatchCreateResponse: ...