Tasks
A task is one goal that the browser agent works on in a session. Modes, step limits and why a task stops.
A task is one goal in plain language, for example "log in and open the billing page". The browser agent looks at the page, decides on an action, does it, and repeats until the goal is done or it has to stop. A task runs in a session.
Start a task with the run_task MCP tool. See Tools. Read stored tasks with get_task, or with GET /v1/sessions/:id/tasks and GET /v1/tasks. Read the report of a task with get_report.
One goal per task
Give one task one clear goal. For a flow with several pages (log in, add to cart, pay), run several tasks on the same session: open the session with create_session (or give the first run_task a startUrl and keepOpen: true), then call run_task once per stage with the same sessionId. The browser keeps its cookies and page between tasks.
A goal is at most 2000 characters. The goal and the answer are stored with the task, so do not put secrets in a goal.
Modes
The mode says how much the agent asks you.
| Mode | Behaviour |
|---|---|
auto | Acts alone and asks only when it is stuck. The default |
full_auto | Never asks. At a hard block it stops instead |
ask | Asks before anything that changes state |
plan | Shows a plan and waits for approval |
run_task offers only auto and full_auto. An MCP call cannot answer a question, so a task that waits would sit idle until it ends as unanswered.
Limits of one task
maxSteps: 1 to 50. The agent uses 25 when you give none.- A cost cap per task. The platform sets it, and the engine of the session may set another. A task that reaches it stops with
stoppedBy: "budget"andlimit: "maxCostUsd". run_taskwaits up to 90 seconds. A longer task keeps running. See Limits.
Why a task stops
Every finished task has ok and stoppedBy. ok is true only when stoppedBy is done.
stoppedBy | Meaning |
|---|---|
done | The agent says it reached the goal. answer holds what it found |
blocked | The agent could not go on: a navigation the guard refused, a site allowlist, or a rule of the mode held the step back. reason says which |
stuck | The agent made no progress |
budget | A limit was reached. limit is maxSteps or maxCostUsd |
captcha | The page showed a CAPTCHA. webagent does not solve CAPTCHAs |
paused | A person took over the session |
aborted | The task was stopped on request, or its time limit ran out |
error | Something failed inside the task. reason says what |
unanswered | A question waited 10 minutes and got no answer |
ok: false is a normal result, not an HTTP error. Over MCP, run_task sets isError only when the agent could not test (captcha, blocked, error, aborted, paused, or a capacity or timeout stop). For a test, treat done as "the agent finished" and read answer to see whether the app behaved as expected. The agent decides when it is done. A task does not check assertions for you. For checks with a fixed pass or fail, use smoke_test, which runs the smoke-uat skill.
What a task returns
A task result has ok, answer, stoppedBy, reason, limit, steps, costMicros and ms. Each step lists its op (click, type, navigate and so on), whether it worked, how long it took, its cost and an error text. Costs are in millionths of a US dollar. A step has no screenshot or page URL of its own. A finished task can carry up to two screenshots: see Task screenshots. See also Evidence.
While a task runs, the stored record has status: "running". When it ends, it is finished.
Task screenshots
After a goal task ends, webagent keeps a screenshot of the last page, and of the page at the first step that failed. A task has at most two. A task that kept none has no screenshots field. A screenshot problem never fails the task.
A stored task (GET /v1/sessions/:id/tasks, GET /v1/tasks, the get_task MCP tool) lists them in screenshots:
"screenshots": [
{ "kind": "final", "url": "https://...", "expiresAt": "2026-11-13T00:05:00.000Z" },
{ "kind": "failed_step", "stepIndex": 3, "url": "https://...", "expiresAt": "2026-11-13T00:05:00.000Z" }
]| Field | Meaning |
|---|---|
kind | final is the page when the task ended. failed_step is the page at the first failed step |
stepIndex | failed_step only: the position of that step, counted from 0 |
url | A signed link. It opens without an API key |
expiresAt | When the link stops working. It is short-lived (about 5 minutes today). Read the task again for new links |
get_task prints them as text too: Screenshot (final state, link expires <time>): <url> and Screenshot of failed step <n>: <url>. The run_task summary has no screenshot line: read the task with get_task after it ends. Screenshots are kept for tasks that ran after this feature was added, so older tasks have none.
The task report
get_report with a task id (tsk_…), or GET /v1/tasks/:id/report.json, returns the same report as a smoke test: a verdict, the steps, and the console errors and failed network calls that happened while the task ran. The verdict is pass when the agent says it is done, error when it stopped for a reason that means it could not test, and fail for the other stops (stuck, budget, unanswered). The report says in notes that a task has no assertions. A task step in the report has only the action and its target. A task report has no findings. It carries the task screenshots: the failed step has a screenshotUrl, and evidence.finalScreenshotUrl is the last page. Both stop working at evidence.urlsExpireAt.
Console errors and failed network calls come from the session log, which is saved when the session ends. Read the report again after the session has ended.