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. Setretries 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.
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.
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 withcleanup_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
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 includessession_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:
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:
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 withretries: 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 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
attemptsarray when you need the total.
Next steps
- Run a Task — execute a task via API with inputs, identity, and session options
- Self-healing — AI fallback during a run and healed drafts afterward
- Webhook events — the full event catalog