Browsing
Browser automation on real devices — natural-language tasks or custom Python scripts.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/browsing/async | Create task, return task_id immediately |
| POST | /api/v1/browsing/sync | Create task, wait for result |
| GET | /api/v1/browsing/status | Poll status and result by task_id |
| GET | /api/v1/browsing/screenshots/{task_id}/{filename} | Download a screenshot file |
Screenshot files are kept for up to 3 days, then deleted automatically.
See API Reference for request/response details.
Task IDs
Browsing tasks use prefix web: (e.g. web:550e8400-e29b-41d4-a716-446655440000).
Request body (summary)
Either task (natural language) or script (custom Python) is required.
{
"task": "Open https://example.com and summarize the page",
"filter": { "country_iso": "DE" },
"screenshots": {
"mode": "final_only",
"full_page": true
},
"fanout": 1,
"timeout": 600000
}| Field | Description |
|---|---|
task | Natural-language instruction |
script | Custom Python snippet — requires API key permission; request access via chat in the dashboard |
filter.country_iso | Route to nodes in a country (e.g. DE, US) |
session_key | Group tasks into a shared session (max 128 chars) |
timeout | Client timeout in ms (max 3 hours) |
fanout | Number of nodes to race (1–10, default 1) |
screenshots.mode | final_only, every_step, or on_navigation |
screenshots.full_page | Full-page capture (default true) |
country_iso_exclude | Exclude countries; RU is added by default |
uv_args | Extra Python packages for custom scripts |
Status values
queued → assigned → running → completed | failed | cancelled
When status is completed, the status response includes success, payload, error, and execution_time_ms.
Custom scripts
For full Python script authoring, see Custom Scripts.