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

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

List Mixture items.

Reference: https://docs.benchling.com/docs/api/benchling-api/mixture/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.
- `authors.anyOf` (string, optional) — Restricts results to those whose author matches any of the specified user or author IDs. 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.
- `entityRegistryIds.anyOf` (string, optional) — Restricts results to those that match any of the specified entity registry IDs. Comma-separated list.
- `fieldset.anyOf` (string, optional) — Restricts results to those whose schema implements any of the specified fieldset API IDs (custom schema interfaces). Comma-separated list.
- `folder.eq` (string, optional) — ID of a folder. Restricts results to its direct children.
- `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.
- `project.eq` (string, optional) — ID of a project. Restricts results to those in the project.
- `registry.eq` (string, optional) — ID of a registry. Restricts results to those registered in this registry. Specifying "null" returns unregistered items.
- `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.
- `systemCategory.anyOf` (string, optional) — Restricts results to those whose schema implements any of the specified system category API IDs (non-exclusive static schema interfaces). Comma-separated list.
- `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 Mixture, optional)
- `nextToken` (string, optional)

## Errors

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

### Mixture

- `__typename` (string, optional)
- `authors` (string, optional, nullable)
- `creator` (PrincipalRef, optional, nullable)
- `aliases` (list of string, optional, nullable)
- `allowMeasuredIngredients` (boolean, optional, nullable) — Derived from the mixture's schema.
- `amount` (string, optional, nullable) — The positive numerical amount value of this mixture in string format (to preserve full precision). Pair with `units`. Supports scientific notation (1.23e4).
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `createdAt` (string, optional, nullable)
- `customFields` (list of CustomField, optional, nullable)
- `entityRegistryId` (string, optional, nullable) — The registry-assigned identifier for this item (e.g. its registry ID shown in the UI), present only once the item has been registered. Null if the item is not registered.
- `folder` (FolderRef, optional, nullable)
- `id` (string, optional)
- `ingredients` (list of Ingredient, optional, nullable) — List of ingredients on this mixture.
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional, nullable) — Name of the item.
- `project` (ProjectRef, optional, nullable)
- `registrationOrigin` (RegistrationOrigin, optional, nullable) — Provenance of this item's registration — where and when it was registered. Null if unregistered.
- `registry` (RegistryRef, optional, nullable) — The Registry this item belongs to, if registered. Null if unregistered.
- `schema` (EntitySchemaRef, optional, nullable) — Use typedSchema instead, which returns the per-type schema.
- `typedSchema` (MixtureSchemaRef, optional, nullable)
- `units` (enum, optional, nullable)
  - Allowed values: `NL`, `UL`, `ML`, `L`, `G`, `KG`, `UNITS`, `UG`, `MG`

### 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)

### Ingredient

Represents a single component within a Mixture, specifying the substance and its amount. Each Ingredient references a componentEntity (the substance being added), an amount with units (see IngredientMeasurementUnits), and optional lot tracking information. The amount can be a numeric value or "QS" (quantum satis, meaning "as much as is needed") for one ingredient per mixture. Ingredients may optionally track component lots either as Container references (for physical inventory tracking) or as text. The targetAmount field is used when a mixture is derived from a parent mixture and indicates the proportional amount needed.

- `__typename` (string, optional)
- `amount` (string, optional, nullable) — The amount value of this ingredient in its mixture, in string format (to preserve full precision). Pair with `units`. Supports scientific notation (1.23e4). One ingredient on this mixture can have an amount value of `"QS"`.
- `catalogIdentifier` (string, optional, nullable)
- `componentEntity` (EntityRef, optional, nullable)
- `componentLotContainer` (ContainerRef, optional, nullable) — The container representing the component lot for this ingredient. This is only present if the mixture schema supports component lots in "storage" format.
- `componentLotEntity` (EntityRef, optional, nullable) — The entity representing the component lot for this ingredient. This is only present if the mixture schema supports component lots in "storage" format.
- `componentLotText` (string, optional, nullable) — Text representing the component lot for this ingredient. This is only present if the mixture schema supports component lots in "text" format.
- `hasParent` (boolean, optional, nullable)
- `notes` (string, optional, nullable)
- `targetAmount` (string, optional, nullable) — The target amount for this ingredient such that this ingredient's proportion in its mixture would preserve the equivalent ingredient's proportion in the parent mixture. Pair with `units`.
- `units` (enum, optional, nullable)
  - Allowed values: `NL`, `UL`, `ML`, `L`, `MG`, `G`, `UNITS`, `CELLS`, `KG`, `MOL`, `UMOL`, `MMOL`, `UG`

### ProjectRef

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

### RegistrationOrigin

Captures the provenance of an entity's registration into the registry. The `originEntry` links to the `DocumentLike` (typically an entry or notebook) from which the entity was registered, providing traceability back to the original experimental context. The `registeredAt` timestamp records when the registration occurred. This information helps scientists understand where registered entities came from and when they were added to the registry.

- `__typename` (string, optional)
- `originEntry` (DocumentLikeRef, optional, nullable)
- `registeredAt` (string, optional, nullable)

### RegistryRef

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

### EntitySchemaRef

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

### MixtureSchemaRef

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

### EntityRef

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

### ContainerRef

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

### DocumentLikeRef

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

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "authors": "authors",
      "aliases": [
        "aliases"
      ],
      "allowMeasuredIngredients": true,
      "amount": "amount",
      "archiveReason": "archiveReason",
      "archived": true,
      "createdAt": "createdAt",
      "customFields": [
        {}
      ],
      "entityRegistryId": "entityRegistryId",
      "id": "id",
      "ingredients": [
        {}
      ],
      "modifiedAt": "modifiedAt",
      "name": "name",
      "units": "NL"
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

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

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

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

print(response.json())
```

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