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

GET https://{tenant_name}.benchling.com/api/v3/dna-sequence/{dna_sequence_id}/annotations/items

List NucleotideAnnotation items.

Reference: https://docs.benchling.com/docs/api/benchling-api/dna-sequence/annotations-list

## Authentication

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

## Request

### Path parameters

- `dna_sequence_id` (string, required) — ID of the DnaSequence.

### Query parameters

- `nextToken` (string, optional) — Token for pagination
- `pageSize` (integer, optional) — Number of results to return. Defaults to 50, maximum of 100.

## Response

### 200

OK

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

## Errors

### 400 Dna Sequence Annotations 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 Dna Sequence Annotations 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 Dna Sequence Annotations 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 Dna Sequence Annotations 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 Dna Sequence Annotations 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

### NucleotideAnnotation

Represents a biological feature annotation on a nucleotide sequence (DNA or RNA). Annotations mark regions of interest such as genes, promoters, terminators, regulatory elements, or other functionally significant sequences. Each annotation specifies a position range (start/end), strand orientation, feature type classification, display color, and descriptive notes. Annotations appear as visual overlays on the sequence viewer and can be created manually, imported from standard formats like GenBank, or generated automatically using FeatureLibraries.

- `__typename` (string, optional)
- `color` (string, optional) — Hex color when displaying the annotation.
- `customFields` (list of CustomField, optional) — Custom fields on the annotation.
- `end` (integer, optional) — 0-based exclusive end index. For ranges ending at the end of a circular sequence, this value is always the length of the sequence, never 0.
- `id` (string, optional) — The ID of the nucleotide annotation.
- `name` (string, optional) — Name of the annotation.
- `notes` (string, optional) — Text notes on the annotation.
- `nucleotideSequence` (NucleotideSequenceRef, optional) — The nucleotide sequence that this annotation belongs to.
- `start` (integer, optional) — 0-based inclusive start index.
- `strand` (enum, optional) — Strand orientation for this annotation. One of `FORWARD`, `REVERSE`, or `STRANDLESS`.
  - Allowed values: `FORWARD`, `REVERSE`, `STRANDLESS`
- `type` (string, optional, nullable) — Feature type of the annotation.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

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

### NucleotideSequenceRef

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

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "color": "color",
      "customFields": [
        {}
      ],
      "end": 1,
      "id": "id",
      "name": "name",
      "notes": "notes",
      "start": 1,
      "strand": "FORWARD",
      "type": "type"
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/dna-sequence/dna_sequence_id/annotations/items"

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

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

print(response.json())
```

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