> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorbrowser.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Task

> Execute an Automation Task via the API — inputs, identity, sessions, sync, and polling.

## 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

<CodeGroup>
  ```javascript node.js theme={null}
  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);
  ```

  ```python python theme={null}
  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'])
  ```
</CodeGroup>

## 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](/essentials/authenticated-applications). |
| `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](/api-reference/browser-sessions/start-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`):

<CodeGroup>
  ```javascript node.js theme={null}
  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 },
        },
      },
    },
  });
  ```

  ```python python theme={null}
  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},
              },
          },
      },
  )
  ```
</CodeGroup>

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](/advanced/proxy), [Session timeout](/advanced/session-timeout), and [CAPTCHA solving](/advanced/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`.

```javascript node.js theme={null}
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 python theme={null}
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")
```

<Tip>
  Use sync for short tasks and scripts. Poll for long-running production runs.
</Tip>

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

## Next steps

* [Creating a Task](/tasks/creating-a-task) — create tasks from a demonstration or prompt
* [Automation Tasks Overview](/tasks/overview) — UI walkthrough of workflows, runs, and self-healing
* [API Reference](/api-reference/tasks/run-a-task) — full endpoint schemas