> 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 Container items

GET https://{tenant_name}.benchling.com/api/v3/container/items

List Container items.

Reference: https://docs.benchling.com/docs/api/benchling-api/container/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.
- `barcode.anyOf` (string, optional) — Restricts results to those matching any of the specified barcodes. Fails and reports any invalid barcodes. 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.
- `creator.anyOf` (string, optional) — Restricts results to those created by any of the specified user IDs. Comma-separated list.
- `id.anyOf` (string, optional) — Restricts results to those matching any of the specified IDs. Comma-separated list.
- `mentionedIn.anyOf` (string, optional) — Restricts results to items mentioned in entries matching any of the specified entry 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.
- `parentStorage.eq` (string, optional) — ID of a location. Restricts results to those located in the specified inventory.
- `returning` (string, optional) — Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
- `schema.anyOf` (string, optional) — Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time. Comma-separated list.
- `schema.eq` (string, optional) — Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time.
- `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`

## Response

### 200

OK

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

## Errors

### 400 Container 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 Container 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 Container 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 Container 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 Container 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

### Container

- `__typename` (string, optional)
- `creator` (PrincipalRef, optional)
- `schemaFields` (list of SchemaFieldValue, optional, nullable)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `barcode` (string, optional, nullable)
- `checkoutRecord` (CheckoutRecord, optional) — Tracks the checkout status of an inventory item such as a Container. When laboratory samples need to be temporarily removed from storage (e.g., for an experiment), users can check them out, optionally adding a comment and assigning responsibility to a user or team (see Assignee). The record captures when the status was last modified. This enables sample tracking workflows and prevents conflicts when multiple users need access to the same samples.
- `contents` (list of ContainerContent, optional)
- `coordinates` (GridCoordinates, optional, nullable) — Coordinates of the container within its contained grid, if it is contained within a grid.
- `createdAt` (string, optional)
- `expirationInfo` (ExpirationInfo, optional) — Expiration info for the container.
- `id` (string, optional)
- `modifiedAt` (string, optional)
- `name` (string, optional)
- `parentStorage` (ObjectRef, optional, nullable) — Union of Box, WellPlate, MatrixPlate, Location
- `parentStorageSchema` (ObjectRef, optional, nullable) — Union of BoxSchema, WellPlateSchema, MatrixPlateSchema, LocationSchema
- `project` (ProjectRef, optional, nullable)
- `quantity` (Measurement, optional, nullable) — Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.
- `role` (ExperimentalRole, optional, nullable) — Represents the complete experimental designation of a well or container within an assay, combining a primary role (see PrimaryExperimentalRole), replicate group number, and optional subrole. The group field identifies replicate sets: wells with the same primary role and group number are treated as technical replicates for statistical analysis. The subrole field provides additional categorization for controls (e.g., POSITIVE, NEGATIVE, MAXIMUM, MINIMUM); only CONTROL primary roles may have subroles. ExperimentalRole is used in plate-based workflows to define experimental layouts (see PlateMapPosition) and annotate wells in FixedPlate and Container objects.
- `schema` (ContainerSchemaRef, optional)
- `gridNumber` (double, optional, nullable, deprecated) — Please use coordinates.index
- `gridPosition` (string, optional, nullable, deprecated) — Please use coordinates.position

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### PrincipalRef

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

### SchemaFieldValue

Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the field's type and constraints) with its actual `value` (a `BenchlingValue` such as text, number, date, or link to another object). The value may be null if no value has been set. Used within the `schemaFields` collection on objects that implement `HasSchema` to provide access to all custom field values defined by the object's schema.

- `__typename` (string, optional)
- `fieldDefinition` (SchemaFieldDefinitionRef, optional)
- `id` (string, optional)
- `linkedEntityId` (string, optional, nullable)
- `value` (SchemaFieldValueValue, optional, nullable) — Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue

### CheckoutRecord

Tracks the checkout status of an inventory item such as a Container. When laboratory samples need to be temporarily removed from storage (e.g., for an experiment), users can check them out, optionally adding a comment and assigning responsibility to a user or team (see Assignee). The record captures when the status was last modified. This enables sample tracking workflows and prevents conflicts when multiple users need access to the same samples.

- `__typename` (string, optional)
- `assignee` (ObjectRef, optional, nullable) — Union of User, Team
- `comment` (string, optional, nullable)
- `modifiedAt` (string, optional, nullable)
- `status` (enum, optional, nullable)
  - Allowed values: `AVAILABLE`, `RESERVED`, `CHECKED_OUT`

### ContainerContent

Represents a biological or chemical entity stored within a Container or well. Each ContainerContent links an Entity (such as a DNA sequence, protein, or custom entity) to its storage location, along with an optional concentration measurement. The timestamps track when the entity was first placed in the container and when the concentration was last modified. A container can hold multiple ContainerContent items representing different entities or samples stored together.

- `__typename` (string, optional)
- `concentration` (Measurement, optional, nullable) — Concentration of the entity in the container.
- `createdAt` (string, optional) — When the container was first filled with this entity.
- `entity` (EntityRef, optional, nullable) — The entity in the container.
- `modifiedAt` (string, optional) — When the entity was last added to this container or the concentration was last changed.

### GridCoordinates

Read model representing a fillable position in a box or plate.

- `__typename` (string, optional)
- `column` (integer, optional) — The 0-indexed column index of the position
- `index` (integer, optional) — The 1-indexed position determined by counting across rows. For example, for a six-well plate: +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+
- `position` (string, optional) — The alphanumeric position, where rows are indexed alphabetically and columns are indexed numerically, starting from "A1"
- `row` (integer, optional) — The 0-indexed row index of the position

### ExpirationInfo

Provides expiration tracking for inventory items such as containers and their contents. The expirationDate may be explicitly set on the container or inherited from the stored entity's properties. The isExpired flag is a computed convenience field that returns true if the current date is past the expiration date. Items without an expiration date are considered non-expiring (isExpired returns false).

- `__typename` (string, optional)
- `expirationDate` (string, optional, nullable) — Expiration date of the item, potentially inherited from the contents or overridden.
- `isExpired` (boolean, optional) — Whether the item is past its expiration date. Items without an expiration date return False.

### ObjectRef

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

### ProjectRef

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

### Measurement

Represents a quantity with an associated unit of measurement within Benchling's inventory system. Measurements are used throughout inventory to track container volumes, sample masses, concentrations, and other quantitative values. Each Measurement pairs a numeric value with a Unit (see Unit) to provide context-aware quantity handling. For example, a container might have a Measurement of 500 uL for its volume. Unlike ContainerQuantity which provides a simpler representation, Measurement supports the full Unit system with dimensional conversions.

- `__typename` (string, optional)
- `unit` (UnitRef, optional, nullable)
- `value` (double, optional, nullable)

### ExperimentalRole

Represents the complete experimental designation of a well or container within an assay, combining a primary role (see PrimaryExperimentalRole), replicate group number, and optional subrole. The group field identifies replicate sets: wells with the same primary role and group number are treated as technical replicates for statistical analysis. The subrole field provides additional categorization for controls (e.g., POSITIVE, NEGATIVE, MAXIMUM, MINIMUM); only CONTROL primary roles may have subroles. ExperimentalRole is used in plate-based workflows to define experimental layouts (see PlateMapPosition) and annotate wells in FixedPlate and Container objects.

- `__typename` (string, optional)
- `group` (integer, optional) — Role group (aka replicate id)
- `primaryRole` (enum, optional) — Primary role
  - Allowed values: `CONTROL`, `SAMPLE`, `BLANK`, `STANDARD`
- `subrole` (string, optional, nullable) — Subrole, used to differentiate different sub types of a role (e.g. positive control)

### ContainerSchemaRef

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

### SchemaFieldDefinitionRef

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

### SchemaFieldValueValue

### EntityRef

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

### UnitRef

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

### BooleanValue

A type that represents boolean values.

- `__typename` (string, optional)
- `value` (boolean, optional) — The boolean value.

### DateTimeValue

A type that represents datetime values.

- `__typename` (string, optional)
- `value` (string, optional) — The datetime value with UTC as the timezone.

### DateValue

A type that represents date values.

- `__typename` (string, optional)
- `value` (date, optional) — The date value.

### DecimalValue

A type that represents decimal value as strings.

- `__typename` (string, optional)
- `value` (string, optional, nullable) — The decimal value in a string representation
- `numericValue` (double, optional, nullable, deprecated) — Deprecated. The float representation of the decimal value.

### IntegerValue

A type that represents integer values.

- `__typename` (string, optional)
- `value` (integer, optional) — The integer value.

### JsonValue

A type that represents JSON values.

- `__typename` (string, optional)
- `value` (map from string to any, optional) — The JSON value.

### ObjectLinkValue

A type that represents links to other objects.

- `__typename` (string, optional)
- `value` (ObjectRef, optional) — The object that this value links to, or an Inaccessible object if not found with the current permission set.

### ObjectLinkListValue

A type that represents a list of links to other objects.

- `__typename` (string, optional)
- `value` (list of ObjectRef, optional) — The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set.

### TextAndUrlValue

A type that represents text (string) values with an associated URL.

- `__typename` (string, optional)
- `url` (string, optional) — The URL associated with the value. Please use `TextValue` if you don't want a URL.
- `value` (string, optional) — The text value. It may or may not be an empty string.

### TextValue

A type that represents text (string) values.

- `__typename` (string, optional)
- `value` (string, optional) — The text value. It may or may not be an empty string.

### ArrayValue

A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).

- `__typename` (string, optional)
- `value` (list of ArrayValueValueItem, optional)

### ArrayValueValueItem

Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "schemaFields": [
        {}
      ],
      "archiveReason": "archiveReason",
      "archived": true,
      "barcode": "barcode",
      "contents": [
        {}
      ],
      "createdAt": "createdAt",
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name"
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/container/items"

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

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

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/container/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);
}
```