> 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.

# List RunSchema items

GET https://{tenant_name}.benchling.com/api/v3/run-schema/items

List RunSchema items.

Reference: https://docs.benchling.com/docs/api/benchling-api/run-schema/list

## Authentication

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

## Request

### Query parameters

- `archiveReason.anyOf` (string, optional) — Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
- `archived.anyOf` (boolean, optional) — If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
- `createdAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
- `createdAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
- `createdAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. \< 2017-04-30.
- `createdAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. \<= 2017-04-30.
- `id.anyOf` (string, optional) — Restricts results to those matching any of the specified IDs. Comma-separated list.
- `modifiedAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
- `modifiedAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
- `modifiedAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. \< 2017-04-30.
- `modifiedAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. \<= 2017-04-30.
- `name.anyOf` (string, optional) — Restricts results to those that match any of the specified names. Case insensitive. Warning - this filter can be non-performant due to case insensitivity. Ensure only one name filter is used at a time. Comma-separated list.
- `name.anyOf.caseSensitive` (string, optional) — Restricts results to those that match any of the specified names. Case sensitive. Ensure only one name filter is used at a time. Comma-separated list.
- `nextToken` (string, optional) — Token for pagination
- `omit` (string, optional) — Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
- `pageSize` (integer, optional) — Number of results to return. Defaults to 50, maximum of 100.
- `returning` (string, optional) — Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
- `sort` (enum, optional, default: modifiedAt:desc) — Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.
  - Allowed values: `createdAt:asc`, `createdAt:desc`, `modifiedAt:asc`, `modifiedAt:desc`

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

## Response

### 200

OK

- `items` (list of RunSchema, optional)
- `nextToken` (string, optional)

## Errors

### 400 Run Schema List 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 Run Schema List 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 Run Schema List 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)

### 429 Run Schema List 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)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Run Schema List 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

### RunSchema

Defines the structure and automation configuration for a category of Runs in Benchling's lab automation system. A RunSchema specifies field definitions for run metadata, input generator configurations (see AutomationInputFileConfig) for creating instrument worklists, and output processor configurations (see AutomationOutputFileConfig) for parsing instrument results. Schemas can be linked to an AutomationTemplate for automated data processing after runs complete. Settings control whether runs can be created from notebooks (allowCreateRunFromNotebook), inserted from the run inbox (allowInsertRunFromInbox), and whether equipment tracking is enabled (shouldRecordEquipment). Each schema is owned by an Organization and has a systemName used for Data Platform integration. RunSchemas define the automation workflow for specific assay types like qPCR, ELISA, or sequencing.

- `__typename` (string, optional)
- `allowCreateRunFromNotebook` (boolean, optional, nullable) — Whether new runs belonging to this schema can be created from the notebook
- `allowInsertRunFromInbox` (boolean, optional, nullable) — Whether runs belonging to this schema can be inserted in the notebook from the Run Inbox
- `archiveReason` (string, optional, nullable) — If the Run is archived, reason for archiving
- `archived` (boolean, optional) — Whether the Run is archived
- `automationInputFileConfigs` (string, optional) — Configurations for automation input generators on this run
- `automationOutputFileConfigs` (string, optional) — Configurations for automation output processors on this run
- `createdAt` (string, optional, nullable)
- `fieldDefinitions` (string, optional) — Defines the metadata fields for runs belonging to this schema
- `id` (string, optional)
- `modifiedAt` (string, optional, nullable) — DateTime the Run Schema was last modified
- `name` (string, optional) — Name of the Run Schema
- `organization` (OrganizationRef, optional, nullable) — Organization the Run Schema belongs to
- `shouldRecordEquipment` (boolean, optional) — Whether runs belonging to this schema should record equipment or not
- `systemName` (string, optional, nullable) — Name for this schema in the Data Platform. For example, the name of the warehouse table is derived from the systemName.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### OrganizationRef

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

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "allowCreateRunFromNotebook": true,
      "allowInsertRunFromInbox": true,
      "archiveReason": "archiveReason",
      "archived": true,
      "automationInputFileConfigs": "automationInputFileConfigs",
      "automationOutputFileConfigs": "automationOutputFileConfigs",
      "createdAt": "createdAt",
      "fieldDefinitions": "fieldDefinitions",
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "shouldRecordEquipment": true,
      "systemName": "systemName"
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/run-schema/items"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/run-schema/items';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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