Run a Task

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 { client, Tasks } from 'anchorbrowser';

client.setConfig({ auth: () => process.env.ANCHOR_API_KEY });

const run = await Tasks.runTask({
  path: { taskId },
  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.tasks.run_task(
    task_id,
    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.

Retries are not a request parameter. retries is stored on the task definition and applies to every run of that task, so it is not accepted in the /run body. Passing session_id does affect it: a run that supplies its own session takes a single attempt regardless of the task’s retries value. See Retries.

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 client.patch({
  url: `/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 { client, Tasks } from 'anchorbrowser';

client.setConfig({ auth: () => process.env.ANCHOR_API_KEY });

// Sync
const syncRun = await Tasks.runTask({
  path: { taskId },
  body: { input_params: { report_name: 'Q1 Summary' }, sync: true },
});

// Async — poll after starting
let status = await Tasks.runTask({
  path: { taskId },
  body: { input_params: { report_name: 'Q1 Summary' } },
});

while (!['success', 'failure', 'timeout', 'cancelled'].includes(status.status)) {
  await new Promise((r) => setTimeout(r, 2000));
  status = await Tasks.getTaskRunStatus({ path: { runId: status.run_id } });
}

python

import os
import time
from anchorbrowser import Anchorbrowser

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

# Sync
sync_run = anchor_client.tasks.run_task(
    task_id,
    input_params={'report_name': 'Q1 Summary'},
    extra_body={'sync': True},
)

# Async — poll after starting
status = anchor_client.tasks.run_task(
    task_id,
    input_params={'report_name': 'Q1 Summary'},
)

while status.status not in ('success', 'failure', 'timeout', 'cancelled'):
    time.sleep(2)
    status = anchor_client.tasks.get_task_run_status(status.run_id)

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.

Retries

retries is set on the task, not per run, so every run of that task uses it. It is an integer from 0 to 10 on task create and update (and in the dashboard Settings tab), and from 0 to 3 on POST /v2/tasks/generate. It defaults to 0, and it counts retries rather than attempts: retries: 2 means one initial attempt plus up to two retries, three attempts in total. Every attempt runs on a brand-new browser session. Nothing carries over from the attempt before it: no cookies, no local storage, no open pages. Retrying stops as soon as an attempt succeeds, and the run reports that attempt’s result. A run emits exactly one webhook. A run that fails and then succeeds sends a single task.completed and zero task.failed. Intermediate attempts never reach your endpoint, so retry logic built on task.failed never sees them. See Webhook events.

Outcome	Retried
Task code failed	Yes
Browser session could not be created	Yes
Run timed out	No
Run was cancelled	No
Identity authentication failed	No

A timed-out or cancelled run has already spent its budget. Identity authentication is excluded because each attempt performs a real login, and repeated failed logins from different IP addresses can lock the account. Passing session_id also forces a single attempt: a retry needs a new browser, and that session belongs to you. GET /v1/executions/{executionId}/metadata returns the run’s metadata, including an attempts array under metadata.attempts ordered by attempt number. It is empty for a run that never retried. Each entry carries its own browserSessionId, so you can open the browser session for any single attempt.

{
  "metadata": {
    "attempts": [
      {
        "attempt": 1,
        "status": "failure",
        "browserSessionId": "5f1c9a3e-1d2b-4f77-9a0e-7c3b8e5d1a44",
        "errorMessage": "Timeout waiting for selector #export-pdf",
        "executionTime": 41230
      },
      {
        "attempt": 2,
        "status": "success",
        "browserSessionId": "b0a7d612-8c44-4a19-bb60-2f9e0c11d7a3",
        "errorMessage": null,
        "executionTime": 28870
      }
    ]
  }
}

Two things are stored per run rather than per attempt. Logs and artifacts are the final attempt’s; earlier attempts’ logs are not retained. Duration is the final attempt’s execution time rather than the sum across attempts, so use the per-attempt timings when you need the total.

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

Introduction

Platform

Integrations

Account

Overview

Basic usage

Request parameters

Task config vs session config

Get results

Retries

Next steps

​Overview

​Basic usage

​Request parameters

​Task config vs session config

​Get results

​Retries

​Next steps

Overview

Basic usage

Request parameters

Task config vs session config

Get results

Retries

Next steps