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

GET https://{tenant_name}.benchling.com/api/v3/protein/{protein_id}/history/items

List ProteinVersion items.

Reference: https://docs.benchling.com/docs/api/benchling-api/protein/fullhistory-list

## Authentication

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

## Request

### Path parameters

- `protein_id` (string, required) — ID of the Protein.

### Query parameters

- `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.
- `nextToken` (string, optional) — Token for pagination
- `pageSize` (integer, optional) — Number of results to return. Defaults to 50, maximum of 100.
- `proteinFullHistory.eq` (string, optional) — ID of the Protein that owns the version.
- `sort` (enum, optional, default: createdAt:asc) — Method by which to order results. Valid sorts are: createdAt (created time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is createdAt:asc.
  - Allowed values: `createdAt:asc`, `createdAt:desc`

### Headers

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

## Response

### 200

OK

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

## Errors

### 400 Protein History 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 Protein History 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 Protein History 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 Protein History 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)

### 500 Protein History 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

### ProteinVersion

A historical snapshot of an `Protein` at a specific point in time, preserving the complete structural state including domains, chains, and HELM notation. Protein versions form a lineage that tracks changes over time. Each version records its creator and creation time. The parent field links to the version this one was derived from. Versions may become out of sync with their constituent entities if underlying sequences change.

- `__typename` (string, optional)
- `chains` (list of ProteinChain, optional) — The chains and associated amino acid sequences on the protein.
- `createdAt` (string, optional) — DateTime this version was created.
- `creator` (PrincipalRef, optional)
- `domains` (list of ProteinDomain, optional) — The domains and associated amino acid sequences on the protein.
- `format` (ProteinFormatRef, optional) — The protein format that defines the structure (domains, chains, interactions) for the protein.
- `id` (string, optional) — ID of the protein version.
- `name` (string, optional) — Name of the protein version.
- `outOfSync` (boolean, optional) — Indicates if constituent domain or chain entities have changed since the protein was last updated.
- `outOfSyncReason` (string, optional, nullable) — Any additional information about why the protein is out of sync.
- `parent` (ProteinVersionRef, optional, nullable) — The parent version of the protein.
- `protein` (ProteinRef, optional) — The protein that owns this version.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ProteinChain

Represents a polypeptide chain within an `Protein`, containing the domain composition. Each chain has a computed label derived from the format.

- `__typename` (string, optional)
- `chainPositions` (list of ProteinFormatChainPosition, optional) — Each chain position of this chain in the protein. If a chain has multiplicity > 1, each chain position will be listed here.
- `domains` (list of ProteinDomain, optional) — Each domain on the chain, ordered according to the format.
- `entity` (AaSequenceRef, optional) — The amino acid sequence entity associated with the chain.
- `label` (string, optional) — Unique label for the chain, computed from the format.
- `type` (enum, optional) — The type of the chain.
  - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING`

### PrincipalRef

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

### ProteinDomain

Represents a domain within an `Protein`, containing the actual amino acid sequence for a specific label. Unlike `ProteinFormatDomain` which is a template, `ProteinDomain` is a concrete instance of the domain and links to the underlying amino acid sequence entity.

- `__typename` (string, optional)
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — Each domain position of this domain in the protein. If this domain appears multiple times in the physical structure of the protein, each domain position will be listed here.
- `entity` (AaSequenceRef, optional) — The amino acid sequence entity associated with the domain.
- `label` (string, optional) — A human-readable label for the domain.
- `type` (enum, optional) — The type of the domain.
  - Allowed values: `VL`, `CL`, `VH`, `VHH`, `CH1`, `CH2`, `CH3`, `CH4`, `J`, `H`, `L`, `VA`, `CA`, `VB`, `CB`, `VG`, `CG`, `VD`, `CD`, `F`, `ELEMENT`

### ProteinFormatRef

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

### ProteinVersionRef

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

### ProteinRef

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

### ProteinFormatChainPosition

Defines each instance of a polypeptide chain within a `ProteinFormat`, specifying the chain type and its constituent domains. Each chain position has a unique ref identifier and lists the domain positions (see `ProteinFormatDomainPosition`) that compose it in order from N-terminus to C-terminus. For example, a heavy chain position might reference domain positions [VH, CH1, Hinge, CH2, CH3].

- `__typename` (string, optional)
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — A list of all the domain positions that make up the chain position, in order
- `ref` (integer, optional) — A unique identifier for a physical component (chain or domain) in a protein format. This is used to form a HELM reference that is used in the protein's complex polymer structure.
- `type` (enum, optional) — Type of the chain.
  - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING`

### AaSequenceRef

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

### ProteinFormatDomainPosition

Defines a domain position within a `ProteinFormat`, specifying the domain type and identity of each physical domain in the protein format. Each domain position has a unique ref identifier used to construct HELM notation for complex polymer structures. Domain positions are grouped into ProteinFormatDomains, and each group can be uniquely identified by its label, and will be a single amino acid sequence entity in proteins of this format.

- `__typename` (string, optional)
- `optional` (boolean, optional) — Whether this domain is optional in the format. If true, entities of this format may not have this domain.
- `ref` (integer, optional) — A unique identifier for a physical component (chain or domain) in a protein format. This is used to form a HELM reference that is used in the protein's complex polymer structure.
- `type` (enum, optional) — Type of the domain
  - Allowed values: `VL`, `CL`, `VH`, `VHH`, `CH1`, `CH2`, `CH3`, `CH4`, `J`, `H`, `L`, `VA`, `CA`, `VB`, `CB`, `VG`, `CG`, `VD`, `CD`, `F`, `ELEMENT`

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "chains": [
        {}
      ],
      "createdAt": "createdAt",
      "domains": [
        {}
      ],
      "id": "id",
      "name": "name",
      "outOfSync": true,
      "outOfSyncReason": "outOfSyncReason"
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/protein/protein_id/history/items"

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

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

print(response.json())
```

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