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

# Poll async task status

GET https://{tenant_name}.benchling.com/api/v3/tasks/aa-sequence/annotate-domains/{task_id}

Poll the status of the "Annotate domains on AA sequences" task.

Annotate registered AA domain sequences with PipeBio, updating the annotations and domain schema fields of each annotated sequence and recording the outcome for every sequence in a new Data Catalog dataset. Existing annotations on domain sequences will be removed and overwritten.

Reference: https://docs.benchling.com/docs/api/benchling-api/aa-sequence/annotatedomains-get

## Authentication

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

## Request

### Path parameters

- `task_id` (string, required) — ID of the asynchronous task to poll.

### Headers

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

## Response

### 200

OK

- `message` (string, required)
- `status` (enum, required)
  - Allowed values: `NOT_STARTED`, `IN_PROGRESS`, `COMPLETED`, `FAILED`
- `result` (AnnotateAaSequenceDomainsOutput, optional, nullable) — Result of annotating domains on AA sequences.

## Errors

### 400 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 Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 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 Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 500 Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### AnnotateAaSequenceDomainsOutput

Result of annotating domains on AA sequences.

- `dataset` (DatasetRef, optional) — Dataset that records the annotation outcome of each AA sequence.
- `results` (list of AaSequenceDomainAnnotationResult, optional) — Annotation outcome of each requested AA sequence, in request order.

### GeneralErrorDetail

- string
- map from string to any

### TooManyRequestsErrorDetail

- string
- map from string to any

### InternalServerErrorDetail

- string
- map from string to any

### DatasetRef

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

### AaSequenceDomainAnnotationResult

Annotation outcome of a single AA sequence.

- `__typename` (string, optional)
- `aaSequence` (AaSequenceRef, optional)
- `errorMessage` (string, optional, nullable) — Why the AA sequence was not annotated. Null when its annotations and domain fields were updated.

### AaSequenceRef

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

## Examples

**Response**

```json
{
  "message": "string",
  "status": "NOT_STARTED",
  "result": {
    "dataset": {
      "__typename": "string",
      "id": "string"
    },
    "results": [
      {
        "__typename": "string",
        "aaSequence": {
          "__typename": "string",
          "id": "string"
        },
        "errorMessage": null
      }
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/tasks/aa-sequence/annotate-domains/task_id"

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

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

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/tasks/aa-sequence/annotate-domains/task_id';
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);
}
```