# Dataset Items ## Add items to an existing dataset `dataset_items.batch_create(DatasetItemBatchCreateParams**kwargs) -> DatasetItemBatchCreateResponse` **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. ### Parameters - `data: Iterable[Dict[str, object]]` Items to be added to the dataset - `dataset_id: str` Identifier of the target dataset - `files: Optional[Iterable[Dict[str, str]]]` Files to be associated to the dataset ### Returns - `class DatasetItemBatchCreateResponse: …` - `items: List[DatasetItem]` - `id: str` The unique identifier of the entity. - `content_hash: str` - `created_at: datetime` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `data: Dict[str, object]` - `updated_at: datetime` The date and time when the entity was last updated in ISO format. - `archived_at: Optional[datetime]` 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"]]` - `"dataset.item"` - `object: Optional[Literal["list"]]` - `"list"` ### Example ```python 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 ) response = client.dataset_items.batch_create( data=[{ "foo": "bar" }], dataset_id="dataset_id", ) print(response.items) ``` #### Response ```json { "items": [ { "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" } ], "object": "list" } ``` ## Get a dataset item `dataset_items.retrieve(strdataset_item_id, DatasetItemRetrieveParams**kwargs) -> 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. ### Parameters - `dataset_item_id: str` - `version: Optional[int]` Optional dataset version. When unset, returns the latest version. ### Returns - `class DatasetItem: …` - `id: str` The unique identifier of the entity. - `content_hash: str` - `created_at: datetime` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `data: Dict[str, object]` - `updated_at: datetime` The date and time when the entity was last updated in ISO format. - `archived_at: Optional[datetime]` 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"]]` - `"dataset.item"` ### Example ```python 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.retrieve( dataset_item_id="dataset_item_id", ) print(dataset_item.id) ``` #### Response ```json { "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" } ``` ## Delete a dataset item `dataset_items.archive(strdataset_item_id) -> 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. ### Parameters - `dataset_item_id: str` ### Returns - `class DatasetItemArchiveResponse: …` - `id: str` - `deleted: bool` - `object: Optional[Literal["dataset.item"]]` - `"dataset.item"` ### Example ```python 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 ) response = client.dataset_items.archive( "dataset_item_id", ) print(response.id) ``` #### Response ```json { "id": "id", "deleted": true, "object": "dataset.item" } ``` ## Update a dataset item `dataset_items.update(strdataset_item_id, DatasetItemUpdateParams**kwargs) -> 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 - `class DatasetItem: …` - `id: str` The unique identifier of the entity. - `content_hash: str` - `created_at: datetime` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `data: Dict[str, object]` - `updated_at: datetime` The date and time when the entity was last updated in ISO format. - `archived_at: Optional[datetime]` 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"]]` - `"dataset.item"` ### Example ```python 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) ``` #### Response ```json { "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" } ``` ## List dataset items `dataset_items.list(DatasetItemListParams**kwargs) -> 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. ### Parameters - `dataset_id: Optional[str]` Optional dataset identifier. Must be provided if a specific version is requested. - `ending_before: Optional[str]` - `include_archived: Optional[bool]` - `limit: Optional[int]` - `sort_by: Optional[str]` - `sort_order: Optional[SortOrder]` - `"asc"` - `"desc"` - `starting_after: Optional[str]` - `version: Optional[int]` Optional dataset version. When unset, returns the latest version. Requires a valid dataset_id when set. ### Returns - `class DatasetItem: …` - `id: str` The unique identifier of the entity. - `content_hash: str` - `created_at: datetime` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `data: Dict[str, object]` - `updated_at: datetime` The date and time when the entity was last updated in ISO format. - `archived_at: Optional[datetime]` 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"]]` - `"dataset.item"` ### Example ```python 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 ) page = client.dataset_items.list() page = page.items[0] print(page.id) ``` #### Response ```json { "has_more": true, "items": [ { "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" } ], "total": 0, "limit": 0, "object": "list" } ``` ## Domain Types ### Dataset Item - `class DatasetItem: …` - `id: str` The unique identifier of the entity. - `content_hash: str` - `created_at: datetime` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `data: Dict[str, object]` - `updated_at: datetime` The date and time when the entity was last updated in ISO format. - `archived_at: Optional[datetime]` 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"]]` - `"dataset.item"` ### Dataset Item Batch Create Response - `class DatasetItemBatchCreateResponse: …` - `items: List[DatasetItem]` - `id: str` The unique identifier of the entity. - `content_hash: str` - `created_at: datetime` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `data: Dict[str, object]` - `updated_at: datetime` The date and time when the entity was last updated in ISO format. - `archived_at: Optional[datetime]` 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"]]` - `"dataset.item"` - `object: Optional[Literal["list"]]` - `"list"` ### Dataset Item Archive Response - `class DatasetItemArchiveResponse: …` - `id: str` - `deleted: bool` - `object: Optional[Literal["dataset.item"]]` - `"dataset.item"`