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

{
  "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):

{ "task_id": "web:..." }

POST /api/v1/browsing/sync

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

Response (JSON):

{
  "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:

{ "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):

{
  "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:

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:

{ "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:

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:

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:

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