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

# Get an agent task

GET https://{tenant_name}.benchling.com/api/v3/tasks/agents/{task_id}

Get an agent task

Reference: https://docs.benchling.com/docs/api/benchling-api/tasks/agent-task-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)

### Headers

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

## Response

### 200

Task status and contents

- `chatId` (string, required)
- `content` (list of AgentTaskGetResponseContentItem, required)
- `status` (enum, required) — Current task status.
  - Allowed values: `NOT_STARTED`, `ACTIVE`, `COMPLETED`, `FAILED`
- `taskId` (string, required)
- `agent` (enum, optional) — Present when the task was created with an explicit legacy agent. Omitted for the default unified-agent path.
  - Allowed values: `benchling_deep_research_v1`, `benchling_ask_v1`, `benchling_ai_v1`
- `artifacts` (list of AgentTaskGetResponseArtifactsItem, optional) — Generated image files represented by file blocks in a completed agent response. Omitted while the task is in progress or when the response has no available generated images. Files that are missing or unavailable because of antivirus scanning are omitted.

## Errors

### 400 Agent Task Get 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 Agent Task Get 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 Agent Task Get 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 Agent Task Get 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 Agent Task Get 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

### AgentTaskGetResponseContentItem

- `content_type` (enum, required) — MIME type of the content.
  - Allowed values: `text/markdown`
- `text` (string, required)

### AgentTaskGetResponseArtifactsItem

- `downloadUrl` (string, required) — Short-lived presigned URL valid for at most 60 seconds after generation, Request the agent task status again to obtain a fresh URL.
- `filename` (string, required)
- `id` (string, required)
- `mediaType` (string, required)
- `type` (enum, required)
  - Allowed values: `file`

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

## Examples

**Response**

```json
{
  "chatId": "chtsess_1234",
  "content": [
    {
      "content_type": "text/markdown",
      "text": "These are the findings..."
    }
  ],
  "status": "COMPLETED",
  "taskId": "atsk_1234",
  "agent": "benchling_deep_research_v1",
  "artifacts": [
    {
      "downloadUrl": "https://example.s3.amazonaws.com/result.png?signature=...",
      "filename": "result.png",
      "id": "efl_1234",
      "mediaType": "image/png",
      "type": "file"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/tasks/agents/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/agents/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);
}
```