API Reference

All requests go to POST https://api.browserworker.app/v1/ with your Bearer token.

---

Execute Task

POST https://api.browserworker.app/v1/

Headers

Header	Required	Value
Authorization	Yes	Bearer YOUR_BEARER_TOKEN
Content-Type	Yes	application/json or multipart/form-data

Request Body

{
  "actions": [                           // required — list of actions to run
    { "openNewTab": "https://example.com" },
    { "click": ".submit-btn" },
    { "screenshot": "viewport" }
  ],
  "workerId": "-Om8E6V_dV3w8mb27ikb",   // optional — target a specific worker
  "timeout": 30000,                      // optional — task timeout in ms
  "config": {
    "actionTimeout": 5000,               // per-action timeout in ms
    "continueOnError": true              // keep going if an action fails
  },
  "session": {
    "preserve": true                     // keep worker reserved after task
  }
}

Parameters

Field	Type	Default	Description
actions	array	required	Actions to execute sequentially
workerId	string	auto-select	Target a specific worker by ID
timeout	number	30000	Task timeout in ms (30 seconds). Max: 60000 (Free), 120000 (Basic+). For longer tasks, use async: true (Standard+ plans).
config.actionTimeout	number	10000	Per-action timeout in ms (10 seconds)
config.continueOnError	boolean	true	Continue executing if an action fails
session	object	—	Session options (see Sessions)
async	boolean	false	Return immediately with taskId (Standard+ plans)

Multipart Form-Data

For binary file uploads, send multipart/form-data with two fields:

payload  →  JSON string: {"actions": [...], "workerId": "..."}
files    →  binary file attachments (one per field)

Reference uploaded files in actions with $file:0, $file:1, etc. See File Upload.

---

Response

Success (200)

{
  "success": true,
  "taskId": "task_eb09bd2804b99ecb_1771839792",
  "workerId": "-Om8GAObZSvE8trPMPZF",
  "workerName": "My PC",
  "data": { "success": true, "url": "https://files.browserworker.app/screenshots/..." },
  "duration": 6388,
  "sessionId": "ses_..."                 // only present if session.preserve was set
}

Field	Description
success	true if the task completed without errors
taskId	Unique task identifier
workerId	The worker that executed the task
workerName	Human-readable worker name
data	Result from the last action (or accumulated results)
duration	Total execution time in milliseconds
sessionId	Session ID (only if session.preserve was set)

Errors

Code	Description
400	Invalid actions or missing required fields
401	Invalid or missing bearer token
403	Worker doesn't belong to you, or feature not on your plan
404	No available workers found
408	Task timed out
409	Worker is busy, offline, or session mismatch
429	Daily task limit reached (Free plan: 50/day)

{
  "error": "Task timed out",
  "taskId": "task_...",
  "workerId": "-Om8GAObZSvE8trPMPZF",
  "timeout": 30000
}

---

Action Format

Each action is an object with a single key (the action name) mapped to its value.

{ "click": "#submit-btn" }                                              // string selector
{ "fill": ["input[name=email]", "user@example.com"] }                  // array
{ "click": "#submit-btn", "options": { "iframe": "#content" } }        // with options
{ "loop": { "each": ".item", "do": [{ "click": "$this" }] } }          // nested (control flow)

Selectors

Both CSS selectors and XPath are supported. XPath is auto-detected when the selector starts with / or //.

{ "click": ".my-button" }                                   // CSS
{ "click": "//button[contains(text(), 'Submit')]" }         // XPath

Options

Most actions accept an options object for additional configuration:

{
  "click": "#submit",
  "options": {
    "timeout": 5000,            // override per-action timeout
    "iframe": "#content-frame", // target element inside an iframe
    "continueOnError": true     // override global continueOnError for this action
  }
}

See each action's documentation for its supported options.