API Reference

Execute Task

Send browser automation actions to a worker.

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

Headers

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

Request Body (JSON)

{
  "actions": [
    { "openNewTab": "https://example.com" },
    { "click": ".submit-btn" },
    { "screenshot": "viewport" }
  ],
  "workerId": "-Om8E6V_dV3w8mb27ikb",
  "timeout": 30000,
  "config": {
    "actionTimeout": 5000,
    "continueOnError": true
  },
  "session": {
    "preserve": true
  }
}

Parameters

Field	Type	Required	Default	Description
actions	array	Yes	—	Array of action objects to execute sequentially
workerId	string	No	auto-select	Target a specific worker by ID
timeout	number	No	30000	Task timeout in ms (clamped to plan max)
config.actionTimeout	number	No	10000	Default per-action timeout in ms
config.continueOnError	boolean	No	true	Continue executing if an action fails
session	object	No	—	Session management options (see Sessions)
files	array	No	—	Files to upload (see File Upload)

Request Body (Multipart Form-Data)

For binary file uploads, use multipart/form-data:

Content-Type: multipart/form-data

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

Success Response (200)

{
  "success": true,
  "taskId": "task_eb09bd2804b99ecb_1771839792",
  "workerId": "-Om8GAObZSvE8trPMPZF",
  "workerName": "My PC",
  "data": {
    "success": true,
    "url": "https://files.browserworker.app/screenshots/..."
  },
  "duration": 6388
}

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)

Error Responses

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

Error Response Body

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

Action Format

Each action is an object with a single key (the action name) and a value:

// String value
{ "click": "#submit-btn" }

// Array value
{ "fill": ["input[name=email]", "user@example.com"] }

// With options
{ "click": "#submit-btn", "options": { "delay": 500, "iframe": "#content" } }

// Nested structure (control flow)
{ "loop": { "each": ".item", "do": [{ "click": "$this" }] } }

Selectors

BrowserWorker supports both CSS selectors and XPath expressions. XPath is auto-detected when the selector starts with / or //.

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

Options

Most actions accept an options object for additional configuration:

{
  "click": "#submit",
  "options": {
    "timeout": 5000,
    "iframe": "#content-frame",
    "continueOnError": true,
    "showClick": true
  }
}

See each action's documentation for supported options.

Health Check

GET https://api.browserworker.app/health

Returns 200 OK — no authentication required.