Skip to main content

​
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

FieldRequiredDefaultDescription
input_paramsYes—Values matching the task’s input schema
identity_idNo—Identity to authenticate before the run. See Identities.
session_idNo—Run inside an existing browser session instead of creating a new one
cleanup_sessionsNotrueEnd the browser session when the run finishes
syncNofalseWait for completion; response includes result or error
version / version_idNolatestTask version to run. List versions with GET /v2/tasks/{taskId}/versions.
identity_skip_validationNo—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 browserWhich config applies
Omit session_id (default)Anchor creates a session using the task’s task_default_browser_configuration
Pass session_idThe 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