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 astreaming_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
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 intoresult. The run is COMPLETED and error is null either way.
Goal met. A single-page product list:
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 usuallyCOMPLETED 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:
status and reason, the same page explains itself:
COMPLETED after 5 steps with error: null, and the only sign of the block was in the text:
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 runFAILED, 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: 3reportsnum_of_steps: 4. Expect one step over the cap. - A run with
max_duration_seconds: 10ran for about 21 seconds. One withmax_duration_seconds: 60ran for 70.
No finish
A run that endsFAILED 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:
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
statussays why.
Handling run results
Put it together by checking the final status first, then the right field for that status: Pythonstatus 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.
Related
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
resultError Codes
Every code and how to handle it
TinyProfiles
Run as a signed-in user