Run a Task - Anchor Browser Docs

Overview

Call POST /v2/tasks/{taskId}/run with input_params matching the task’s input schema. The response includes run_id and status. By default runs are async — poll for the result, or set sync: true to block until completion.

Basic usage

import AnchorBrowser from 'anchorbrowser';

const anchorClient = new AnchorBrowser({ apiKey: process.env.ANCHOR_API_KEY });

const run = await anchorClient.post(`/v2/tasks/${taskId}/run`, {
  body: {
    input_params: { report_name: 'Monthly Invoice - February 2026' },
  },
});

console.log('Run ID:', run.run_id, 'Status:', run.status);

import os
from anchorbrowser import Anchorbrowser

anchor_client = Anchorbrowser(api_key=os.getenv('ANCHOR_API_KEY'))

run = anchor_client.post(
    f'/v2/tasks/{task_id}/run',
    body={'input_params': {'report_name': 'Monthly Invoice - February 2026'}},
)

print('Run ID:', run['run_id'], 'Status:', run['status'])

Request parameters

Field	Required	Default	Description
`input_params`	Yes	—	Values matching the task’s input schema
`identity_id`	No	—	Identity to authenticate before the run. See Identities.
`session_id`	No	—	Run inside an existing browser session instead of creating a new one
`cleanup_sessions`	No	`true`	End the browser session when the run finishes
`sync`	No	`false`	Wait for completion; response includes `result` or `error`
`version` / `version_id`	No	latest	Task version to run. List versions with `GET /v2/tasks/{taskId}/versions`.
`identity_skip_validation`	No	—	Skip identity validation before the run

input_params keys must match names from the task’s input schema. Pass cleanup_sessions: false with session_id to keep the session open for follow-up work.

Task config vs session config

Browser settings — proxy, viewport, profile, timeouts, CAPTCHA solver — live in a session config: a session block and a browser block, same schema as starting a browser session. A task stores its own copy of that schema as task_default_browser_configuration. This is not sent on each run request. It tells Anchor how to configure the browser when it creates a session for you.

How the run gets a browser	Which config applies
Omit `session_id` (default)	Anchor creates a session using the task’s `task_default_browser_configuration`
Pass `session_id`	The existing session’s config — created earlier via `POST /v1/sessions` or another run

Set task defaults once with PATCH /v1/tools/{toolId} (or task_browser_default_configuration on POST /v2/tasks/generate):

await anchorClient.patch(`/v1/tools/${toolId}`, {
  body: {
    human_intervention: true,
    task_default_browser_configuration: {
      session: {
        timeout: { max_duration: 30 },
        proxy: { active: true, type: 'anchor_residential', country_code: 'US' },
      },
      browser: {
        captcha_solver: { active: true },
        profile: { name: 'my-task-profile', persist: true },
      },
    },
  },
});

anchor_client.patch(
    f'/v1/tools/{tool_id}',
    body={
        'human_intervention': True,
        'task_default_browser_configuration': {
            'session': {
                'timeout': {'max_duration': 30},
                'proxy': {'active': True, 'type': 'anchor_residential', 'country_code': 'US'},
            },
            'browser': {
                'captcha_solver': {'active': True},
                'profile': {'name': 'my-task-profile', 'persist': True},
            },
        },
    },
)

Set task_default_browser_configuration to null to clear it. Per-run, the only session-related fields on /run are session_id (use an existing session) and identity_id (authenticate that session). Everything else comes from the task default or the session you created. See Proxy, Session timeout, and CAPTCHA solving for common session and browser options.

Get results

Sync — add "sync": true to the run request. The response includes result on success or error on failure. Async (default) — poll GET /v2/tasks/runs/{runId}/status until status is success, failure, timeout, or cancelled.

node.js

import AnchorBrowser from 'anchorbrowser';

const anchorClient = new AnchorBrowser({ apiKey: process.env.ANCHOR_API_KEY });

// Sync
const syncRun = await anchorClient.post(`/v2/tasks/${taskId}/run`, {
  body: { input_params: { report_name: 'Q1 Summary' }, sync: true },
});

// Async — poll after starting
let status = await anchorClient.post(`/v2/tasks/${taskId}/run`, {
  body: { input_params: { report_name: 'Q1 Summary' } },
});

while (!['success', 'failure', 'timeout', 'cancelled'].includes(status.status)) {
  await new Promise((r) => setTimeout(r, 2000));
  status = await anchorClient.get(`/v2/tasks/runs/${status.run_id}/status`);
}

python

import os
import time
from anchorbrowser import Anchorbrowser

anchor_client = Anchorbrowser(api_key=os.getenv('ANCHOR_API_KEY'))

# Sync
sync_run = anchor_client.post(
    f'/v2/tasks/{task_id}/run',
    body={'input_params': {'report_name': 'Q1 Summary'}, 'sync': True},
)

# Async — poll after starting
status = anchor_client.post(
    f'/v2/tasks/{task_id}/run',
    body={'input_params': {'report_name': 'Q1 Summary'}},
)

while status['status'] not in ('success', 'failure', 'timeout', 'cancelled'):
    time.sleep(2)
    status = anchor_client.get(f"/v2/tasks/runs/{status['run_id']}/status")

Use sync for short tasks and scripts. Poll for long-running production runs.

Tasks with output file only may return the file in the HTTP body when sync: true instead of JSON.

Next steps

Creating a Task — create tasks from a demonstration or prompt
Automation Tasks Overview — UI walkthrough of workflows, runs, and self-healing
API Reference — full endpoint schemas

​Overview

​Basic usage

​Request parameters

​Task config vs session config

​Get results

​Next steps

Overview

Basic usage

Request parameters

Task config vs session config

Get results

Next steps