Async Execution

By default, BrowserWorker waits for the task to finish before responding. In async mode the server replies immediately with a taskId — the worker continues running in the background and the result is saved when done.

Plan Requirement

Async execution is available on Standard and Pro plans only.

How It Works

1. Send a request with "async": true
2. Server responds immediately with taskId and workerId
3. Worker executes all actions in the background
4. Poll GET /v1/get-result with the taskId to retrieve the result

---

Send an Async Task

Add "async": true to any request body.

cURL

curl -X POST https://api.browserworker.app/v1/ \
  -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      { "open": "https://example.com" },
      { "screenshot": "viewport" }
    ],
    "async": true
  }'

JavaScript

const response = await fetch('https://api.browserworker.app/v1/', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer <YOUR_BEARER_TOKEN>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        actions: [
            { open: 'https://example.com' },
            { screenshot: 'viewport' },
        ],
        async: true,
    }),
});

const { taskId } = await response.json(); // save taskId to poll later

PHP

$ch = curl_init('https://api.browserworker.app/v1/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_BEARER_TOKEN>',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'actions' => [
            ['open' => 'https://example.com'],
            ['screenshot' => 'viewport'],
        ],
        'async' => true,
    ]),
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

$taskId = $result['taskId']; // save taskId to poll later

Python

import requests

response = requests.post(
    'https://api.browserworker.app/v1/',
    headers={'Authorization': 'Bearer <YOUR_BEARER_TOKEN>'},
    json={
        'actions': [
            {'open': 'https://example.com'},
            {'screenshot': 'viewport'},
        ],
        'async': True,
    },
)

task_id = response.json()['taskId']  # save task_id to poll later

Response:

{
  "success": true,
  "async": true,
  "taskId": "task_abc123...",
  "workerId": "-Om8E6V_dV3w8mb27ikb",
  "workerName": "My Worker"
}

---

Get the Result

Poll GET /v1/get-result?taskId=... until success is true. A polling interval of 3–5 seconds is recommended.

cURL

curl -X GET "https://api.browserworker.app/v1/get-result?taskId=task_abc123..." \
  -H "Authorization: Bearer <YOUR_BEARER_TOKEN>"

JavaScript

const taskId = 'task_abc123...';

const result = await new Promise((resolve) => {
    const interval = setInterval(async () => {
        const res = await fetch(`https://api.browserworker.app/v1/get-result?taskId=${taskId}`, {
            headers: { 'Authorization': 'Bearer <YOUR_BEARER_TOKEN>' },
        });
        const data = await res.json();

        if (data.success) {
            clearInterval(interval);
            resolve(data);
        }
    }, 5000); // poll every 5 seconds
});

PHP

$taskId = 'task_abc123...';

while (true) {
    $ch = curl_init("https://api.browserworker.app/v1/get-result?taskId=$taskId");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer <YOUR_BEARER_TOKEN>'],
    ]);

    $result = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if ($result['success']) {
        print_r($result);
        break;
    }

    sleep(5); // poll every 5 seconds
}

Python

import time
import requests

task_id = 'task_abc123...'

while True:
    response = requests.get(
        'https://api.browserworker.app/v1/get-result',
        params={'taskId': task_id},
        headers={'Authorization': 'Bearer <YOUR_BEARER_TOKEN>'},
    )

    result = response.json()

    if result.get('success'):
        print(result)
        break

    time.sleep(5)  # poll every 5 seconds

When complete:

{
  "success": true,
  "taskId": "task_abc123...",
  "workerId": "-Om8E6V_dV3w8mb27ikb",
  "workerName": "My Worker",
  "data": { "success": true, "url": "https://files.browserworker.app/screenshots/..." },
  "duration": 5234
}

When still pending:

{
  "success": false,
  "status": "pending"
}

note

Results are cached for 1 hour after completion. After that, they are automatically deleted.