> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Batch update Dataset

PATCH https://{tenant_name}.benchling.com/api/v3/dataset:batch-update
Content-Type: application/json

Batch update Dataset synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/dataset/batchupdate

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `items` (list of UpdateDatasetInputWithPathParams, required)

## Response

### 200

OK

- `items` (list of Dataset, required)

## Errors

### 400 Dataset Batch Update Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Dataset Batch Update Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Dataset Batch Update Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 409 Dataset Batch Update Request Conflict Error

Conflict

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Dataset Batch Update Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 500 Dataset Batch Update Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### UpdateDatasetInputWithPathParams

- `id` (string, required)
- `allowCustomFieldDeletion` (boolean, optional) — When true, custom fields present on the object but omitted from the update payload will be deleted. When false or omitted, omitting existing custom fields is an error. Defaults to false.
- `archiveReason` (string, optional)
- `archived` (boolean, optional)
- `customFields` (map from string to any, optional)
- `folderId` (string, optional)
- `name` (string, optional)

### Dataset

`Dataset` stores non-schematized tabular data, with Benchling-aware column types. Datasets are first-class, searchable, archivable folder items. A Dataset's actual data is stored in a `DataFrame`.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `createdAt` (string, optional)
- `creator` (PrincipalRef, optional)
- `customFields` (list of CustomField, optional, nullable)
- `dataFrameId` (string, optional, nullable)
- `displayId` (string, optional, nullable) — A human-readable identifier for this dataset (e.g. "DATASET-1"). Automatically generated and unique within the tenant.
- `folder` (FolderRef, optional)
- `id` (string, optional)
- `modifiedAt` (string, optional)
- `name` (string, optional, nullable)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### PrincipalRef

- `__typename` (string, optional)
- `id` (string, optional)

### CustomField

A name-value pair for storing additional metadata on objects that support custom fields. CustomFields provide a flexible way to attach arbitrary string data to entities, containers, datasets, and other Benchling objects without modifying their schemas. Objects that can have custom fields implement the HasCustomFields interface. Unlike schema-defined fields, custom fields are not validated against a schema and can be freely added or modified.

- `__typename` (string, optional)
- `name` (string, optional, nullable)
- `value` (string, optional, nullable)

### FolderRef

- `__typename` (string, optional)
- `id` (string, optional)

## Examples

**Request**

```json
{
  "items": [
    {
      "id": "id"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "createdAt": "createdAt",
      "customFields": [
        {}
      ],
      "dataFrameId": "dataFrameId",
      "displayId": "displayId",
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/dataset:batch-update"

payload = { "items": [{ "id": "id" }] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/dataset:batch-update';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"id":"id"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```