Skip to main content
A run is one execution of a goal in a browser. Every call to the Web Agent creates a run, and the run moves through a fixed set of statuses until it reaches one of three final ones: COMPLETED, FAILED, or CANCELLED. The status tells you whether the run finished. It doesn’t tell you whether the goal was met, or why the agent stopped. That’s the most important thing to understand about runs, and most of this page is about it.

Run lifecycle

A run only moves forward. Once it reaches a final status it never changes again, so you can stop polling as soon as you see one. While a run is PENDING or RUNNING, result and num_of_steps are null and streaming_url shows the live browser. When it reaches a final status, finished_at and num_of_steps are filled in, and the recording moves to video_url. How you see the lifecycle depends on the endpoint you used. /run waits and returns only the final run, so you never see the earlier statuses and you can’t cancel it. /run-async and /run-batch return a run_id straight away for you to poll. /run-sse streams events (STARTED, STREAMING_URL, PROGRESS, HEARTBEAT, then COMPLETE with the final status). Runs from these three can be cancelled. See Endpoints. A request that’s rejected before it starts, such as a bad API key, a malformed body, or a wallet that can’t cover the run, returns an HTTP error and doesn’t create a run at all. In an organization, which runs a key can list and cancel depends on the kind of key. See Who sees what.

Watching runs live

Every run has a streaming_url where you can watch the browser in real time. It’s useful for debugging, for demos, and for telling a slow run from a stuck one. It works while the run is active. Once the run reaches a final status, use video_url on the run object for the recording instead. That link is signed and expires after 15 minutes, so fetch the run again when you need it.

COMPLETED doesn’t mean the goal succeeded

COMPLETED means the run finished, not that it did what you asked. Always check result.
The agent decides when it’s done. If it gets everything you asked for, it returns the data. If it can’t, because the page wants a login, a bot check stops it, or it runs out of steps, it usually still ends the run normally and writes what happened into result. The run is COMPLETED and error is null either way. Goal met. A single-page product list:
Goal not met. A five-page product list with a 3-step limit:
Both of these returned a status and reason inside result because the request included an output schema asking for them. Without one, the explanation comes back as free text in result, worded however the agent chose. The next section explains why that matters.

How a run ends

There are a handful of reasons a run stops, and each one needs a different response from you. These are the finish reasons:

There is no finish-reason field

The API doesn’t return the finish reason as a field. For the first four reasons, the run is usually COMPLETED with error: null, and the reason is only in result. Here’s the same login page twice. Without an output schema, the field you asked for is just empty:
With an output schema that asks for a status and reason, the same page explains itself:
A bot check looks the same. On a review page behind bot protection, with the default browser and no schema, the run ended COMPLETED after 5 steps with error: null, and the only sign of the block was in the text:
This is why the reliable way to get a finish reason is to ask for one. Add a status field with the reasons you care about (success, auth_required, blocked, incomplete) and a reason field to your output schema, and say in the goal what each one means. Your code can then branch on a value instead of reading prose. Keep only status and reason required: if a data field is required and the agent can’t reach the data, it fills the field with a placeholder rather than leave it out. Troubleshoot Runs has the full schema and goal.

Sometimes the run fails instead

The same three problems can also end a run FAILED, with an error code that names them — but error.code is only returned by the synchronous /run endpoint. Polling runs.get and the SSE stream don’t include code, only error.category, which doesn’t distinguish between these three (all three fall under AGENT_FAILURE): A run that a TinyProfile could fix may also carry a profile_hint, with a reason of auth_wall or bot_challenge, a message, and a setup_url that opens profile setup for that site. On a COMPLETED run — the auth-required or blocked case above — it’s a top-level field next to result. On a FAILED run it sits inside error instead. It’s the closest thing the API has to a finish-reason field, but it only appears when a profile would actually help, not on every auth wall or block. So handle both: check error (and error.profile_hint) when the run failed, and your schema’s status plus the top-level profile_hint when it completed.

How the limits end a run

max_steps and max_duration_seconds don’t cut a run off mid-step. When either runs out, the agent takes one more step to write up what it has, then ends the run COMPLETED:
  • A run with max_steps: 3 reports num_of_steps: 4. Expect one step over the cap.
  • A run with max_duration_seconds: 10 ran for about 21 seconds. One with max_duration_seconds: 60 ran for 70.
The write-up says how far the agent got, but on a long run it can leave out the data itself. A 20-page product list with a 60-second limit came back with this:
Treat a budget-exhausted result as a record of where the run stopped, not as the data. Goals that fit inside their limits don’t have this problem, which is why splitting a big goal into small runs works better than raising the limit. See Agent Mode, Max Steps, and Max Duration for what each limit is for.

No finish

A run that ends FAILED or CANCELLED has result: null, so there’s nothing to read except error. error.category tells you how to react: One case needs care: a cancelled run also has an error, but its category depends on why it was cancelled. A run stopped on purpose (yours or a cancel request) carries category: "UNKNOWN". A run cancelled by the billing check carries category: "BILLING_FAILURE" instead — check error.category, not just status, before deciding whether to retry. Here’s a run cancelled about a minute after it started:
If your code retries on UNKNOWN, check status first, or it will restart runs that were stopped on purpose. Cancelling also discards the run’s work: the result is null even if the agent had collected data before the cancel. The full list of codes is in Error Codes.

Who runs into which

Which finish reason you hit depends mostly on the kind of site and task:
  • Auth required comes up most when the task is in your own account: an admin dashboard, a Google or Microsoft form you’re creating or editing, or a job application. Those pages need a signed-in session, so plan for a TinyProfile or Vault from the start.
  • Blocked comes up most on travel, shopping, review, and social sites, which use bot protection heavily. Price comparisons and collecting posts or reviews hit it often.
  • Budget exhausted and no finish come up most on long, multi-site work, such as comparing prices across several sites or paging through a long list in one run. Splitting the work into one run per site or page avoids both.
  • Single-page extraction with an output schema, which is most API and SDK use, mostly ends in success. When it doesn’t, the schema’s status says why.

Handling run results

Put it together by checking the final status first, then the right field for that status: Python
TypeScript
This assumes an output schema with a status field, as described above. To see the steps the agent took before it ended, read steps on GET /v1/runs/{id}. Each step has a timestamp, a status, and the action taken, and screenshots are available per step. See Runs Reference.

Agent mode and limits

agent_config controls how the agent behaves (mode) and how far it’s allowed to go (max_steps, max_duration_seconds). See Agent Mode, Max Steps, and Max Duration for when to use each. Runs can also sign in to sites. Pass use_profile: true to start from a saved TinyProfile, or use_vault: true (and optionally credential_item_ids) to log in with credentials from your connected password manager. See TinyProfiles and Vault Credentials.

Troubleshoot Runs

Fix each finish reason

Recover Stuck Runs

Stop, recover, and split long runs

Runs Reference

List, get, cancel, batch, and per-step screenshots and HTML

Endpoints

Choose sync, async, batch, or streaming

Agent Mode, Max Steps, and Max Duration

Default vs Strict mode, step and time limits

Structured output

Define the shape of result

Error Codes

Every code and how to handle it

TinyProfiles

Run as a signed-in user