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

> ## Agent Instructions
> AI agents that need Anchor credentials should start with https://docs.anchorbrowser.io/quickstart/agent-access. This flow lets agents obtain an API key programmatically without creating a dashboard account. Read that page before attempting authentication or API access.

# Task Retries

> Retry a failed Automation Task run on a brand-new browser, up to three times.

## Overview

A run can fail for reasons that have nothing to do with the task itself: a slow page, a dropped connection, a browser that never came up. Set `retries` on the task and Anchor runs it again when that happens. Each retry starts on a brand-new browser.

`retries` belongs to the **task definition**, not to an individual run. Set it once and every run of that task uses it.

|          |                                                                                                |
| -------- | ---------------------------------------------------------------------------------------------- |
| Type     | Integer                                                                                        |
| Range    | `0` to `3`                                                                                     |
| Default  | `0`                                                                                            |
| Set from | Task create, task update, `POST /v2/tasks/generate`, and the **Settings** tab in the dashboard |

The value counts retries, not attempts. `retries: 2` means one initial attempt plus up to two retries, so three attempts in total. `retries: 0` keeps today's behavior: the run fails the first time it fails.

| `retries`     | Attempts at most |
| ------------- | ---------------- |
| `0` (default) | 1                |
| `1`           | 2                |
| `2`           | 3                |
| `3`           | 4                |

## How a retry works

Every attempt gets its own browser session. Nothing carries over from the attempt before it: no cookies, no local storage, no open pages, no page state. A retry starts from the same place the first attempt did.

Anchor deletes the failed browser before starting the next attempt, so a run that retries twice does not leave two browsers running. This applies even when the run was started with `cleanup_sessions: false`, which only governs the session the run finishes on.

Retrying stops as soon as an attempt succeeds. The run reports that attempt's result.

## What is not retried

| 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 run that timed out has already spent its budget, and a cancelled run was stopped on purpose. Neither is worth attempting again.

Identity authentication is excluded for a different reason. Each attempt performs a real login on the target site. Three failed logins within a few minutes, from three different IP addresses, is a good way to get the account locked. Anchor fails the run instead.

### Runs that supply their own session

When the run request includes `session_id`, the run takes a single attempt regardless of what `retries` says. A retry means a new browser, and in that case the browser belongs to you, so Anchor cannot replace it.

## Setting it

In the dashboard, open the task, go to **Settings**, and pick a value under **Retries**. `Off` is the same as `0`.

Via API, on an existing task:

<CodeGroup>
  ```javascript node.js theme={null}
  await client.put({
    url: `/v1/task/${taskId}`,
    body: { retries: 2 },
  });
  ```

  ```python python theme={null}
  anchor_client.put(
      f'/v1/task/{task_id}',
      body={'retries': 2},
  )
  ```
</CodeGroup>

You can also set `retries` at creation time on `POST /v2/tasks/generate`. `GET /v1/task/{taskId}` returns the current value as `retries`.

## Inspecting attempts

Each attempt is recorded on its own. `GET /v1/executions/{executionId}/metadata` returns them as an `attempts` array ordered by attempt number:

```json theme={null}
{
  "metadata": {
    "taskExecutionStatus": "success",
    "attempts": [
      {
        "attempt": 1,
        "status": "failure",
        "browserSessionId": "5f1c9a3e-1d2b-4f77-9a0e-7c3b8e5d1a44",
        "errorMessage": "Timeout waiting for selector #export-pdf",
        "executionTime": 41230,
        "startedAt": "2026-02-11T09:14:02.118Z",
        "endedAt": "2026-02-11T09:14:43.348Z"
      },
      {
        "attempt": 2,
        "status": "success",
        "browserSessionId": "b0a7d612-8c44-4a19-bb60-2f9e0c11d7a3",
        "errorMessage": null,
        "executionTime": 28870,
        "startedAt": "2026-02-11T09:14:45.902Z",
        "endedAt": "2026-02-11T09:15:14.772Z"
      }
    ]
  }
}
```

The array 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.

In the dashboard, a run that took more than one attempt shows an **N attempts** badge in the runs list, and the run page breaks out every attempt with its status, duration, and browser session.

## Webhooks

**A run emits exactly one webhook, whatever happened along the way.** A run with `retries: 2` that fails, fails again, then succeeds sends a single `task.completed` and zero `task.failed`.

This matters if you built your own retry logic on top of `task.failed`. Intermediate attempts never reach your endpoint, so a run that eventually succeeded produces no failure event to react to, and no run is counted twice. See [Webhook events](/webhooks/events) for the full catalog.

## Limitations

Two things are stored per run rather than per attempt:

* **Logs and artifacts.** Every attempt writes to the same run, so what you read back is the last attempt's output. Earlier attempts' logs are not retained.
* **Duration.** The run's reported execution time is the final attempt's, not the sum across all attempts. Use the per-attempt timings in the `attempts` array when you need the total.

## Next steps

* [Run a Task](/tasks/run-a-task) — execute a task via API with inputs, identity, and session options
* [Self-healing](/advanced/self-healing) — AI fallback during a run and healed drafts afterward
* [Webhook events](/webhooks/events) — the full event catalog