> ## Documentation Index
> Fetch the complete documentation index at: https://dat-48188875.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Browsing

> Browser automation tasks (async/sync/status)

## Endpoints

* **`POST /api/v1/browsing/async`** — create a task and return `task_id` immediately
* **`POST /api/v1/browsing/sync`** — create a task and wait for the result
* **`GET /api/v1/browsing/status?task_id=...`** — get task status (and result if ready)
* **`GET /api/v1/browsing/screenshots/{task_id}/{file}`** — download a screenshot file for a browsing task

## `POST /api/v1/browsing/async`

Creates a browsing task and returns an ID.

Request body (JSON):

```json theme={null}
{
  "task": "Open https://example.com and summarize the page",
  "filter": {
    "country_iso": "DE"
  },
  "screenshots": {
    "mode": "final_only",
    "full_page": true
  }
}
```

* **`task`** *(string, required)* — the instruction to execute in the browser.
* **`screenshots`** *(object, optional)* — enables screenshot collection for the task.
  * **`mode`** *(string, required when `screenshots` is present)* — screenshot capture mode:
    * `final_only` — return a single final screenshot after the task completes
    * `every_step` — return screenshots captured during each browser-use step
    * `on_navigation` — return screenshots only for steps where the page URL changed
  * **`full_page`** *(boolean, optional, default `true`)* — used by `final_only`; captures the full scrollable page instead of only the visible viewport.
  * Screenshot files are temporary and are retained for no more than 5 days.
* **`session_key`** *(string, optional)* — groups browsing tasks into a shared session for node-selection logic.
* **`filter`** *(object, optional)* — constrains which browsing node may receive the task.
  * **`country_iso`** *(string, optional)* — route only to browsing-eligible nodes from the given ISO country code (for example `DE`, `US`).
  * **`node_uid`** *(string, optional)* — route to one specific browsing node by node UID.
  * `country_iso` and `node_uid` are mutually exclusive; specify only one selector.
* **`timeout`** *(integer, optional)* — task timeout in milliseconds (maximum 3 hours).
* **`fanout`** *(integer, optional)* — number of nodes to race the task on (default `1`, allowed range `1..10`).
* **`template`** *(string, optional)* — browsing template stem. If omitted, the default browsing template is used.

Response (JSON):

```json theme={null}
{ "task_id": "web:..." }
```

## `POST /api/v1/browsing/sync`

Same request body as `async`, but waits for completion (up to \~10 minutes).

Response (JSON):

```json theme={null}
{
  "task_id": "web:...",
  "success": true,
  "payload": "{\"result\":\"Page summary\",\"screenshots\":[{\"url\":\"/api/v1/browsing/screenshots/web:.../screenshot-01.png\"}]}",
  "execution_time_ms": 12345
}
```

If the task failed, an additional field may be present:

```json theme={null}
{ "error": "..." }
```

## `GET /api/v1/browsing/status?task_id=...`

Returns task status. If the task is finished (`completed`/`failed`), the response may also include `success`, `payload`, `info`, `error`, `execution_time_ms`.

Example response (JSON):

```json theme={null}
{
  "task_id": "web:...",
  "status": "running",
  "created_at": "2026-02-17T10:00:00Z",
  "assigned_at": "2026-02-17T10:00:05Z",
  "started_at": "2026-02-17T10:00:10Z"
}
```

Possible `status` values:

* `queued`
* `assigned`
* `running`
* `completed`
* `failed`

## `GET /api/v1/browsing/screenshots/{task_id}/{file}`

Downloads a screenshot produced by a browsing task. This endpoint requires the same `Authorization: Bearer ...` header as the browsing API itself.
Screenshot files are retained for no more than 5 days and may return `404` after cleanup.

Example:

```bash theme={null}
curl -sS -X GET "https://llm.dat.ai/api/v1/browsing/screenshots/web:YOUR_TASK_ID/screenshot-01.png" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o screenshot-01.png
```

## Errors

Error format:

```json theme={null}
{ "error": "..." }
```

Typical status codes:

* **400**: invalid JSON / missing `task` / missing `task_id` (status).
* **401**: missing/invalid API key.
* **403**: the task belongs to a different user.
* **404**: task not found.
* **405**: method is not allowed.
* **504**: sync wait timeout.

## `curl` examples

Async:

```bash theme={null}
curl -sS -X POST "https://llm.dat.ai/api/v1/browsing/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Open https://example.com and return a screenshot of the page.",
    "filter": {
      "country_iso": "DE"
    },
    "screenshots": {
      "mode": "final_only",
      "full_page": true
    }
  }'
```

Sync:

```bash theme={null}
curl -sS -X POST "https://llm.dat.ai/api/v1/browsing/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Open https://vk.ru. Wait until the page is loaded. Then change the site language to English. Return the result.",
    "screenshots": {
      "mode": "every_step",
      "full_page": true
    }
  }'
```

Status:

```bash theme={null}
curl -sS -X GET "https://llm.dat.ai/api/v1/browsing/status?task_id=web:YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```