Executions

The lifecycle of a run, what a completed run returns, and the eleven ways a run can fail.

An execution is one agent run on the connected account, from your prompt, in its own isolated session in the cloud. You start it with one call, it's queued, it runs, and it ends either COMPLETED with a result or FAILED with a reason.

Runs use the connection's saved sign-in, so the user doesn't need to sign in for every prompt while that session remains valid. Each run performs its task against the website's current state. The shared discovery cache helps users reach sign-in during authorization; it doesn't replay completed tasks or reuse another user's results.

The lifecycle

status is the job state: QUEUED, RUNNING, COMPLETED, or FAILED. Poll on it until the run is over. On COMPLETED, result holds what the run produced. On FAILED, terminal.status names the reason and terminal.reason explains it in plain words. A completed run's terminal.status is verified, with what WOOL confirmed in terminal.reason.

What success means

A run is COMPLETED only when the agent did what your prompt asked and WOOL confirmed the result against the page. The check is independent of the agent, so an agent can't mark its own work done. If the agent finishes but WOOL can't confirm the result, the run fails with unverified.

Failure reasons

`terminal.status`	The run failed because
`unverified`	The agent finished, but WOOL couldn't confirm the result against the page.
`not_possible`	The task can't be done on this account or page.
`needs_user`	The site asked for something only the user can give, such as a CAPTCHA.
`session_expired`	The website signed the account out. The connection needs re-authorization.
`site_error`	The website kept failing: server errors, blocks, or rate limits.
`blocked_policy`	The prompt asked for something outside what the connection allows.
`budget_exhausted`	The run used its allowance of time and actions before finishing.
`no_progress`	The run stopped making progress and was ended.
`timed_out`	The run hit its time limit.
`provider_failed`	An upstream provider failed. Nothing about the prompt caused it.
`browser_error`	The isolated session couldn't start or resume.

Handling failures says what your code should do for each.

The result

result is present on COMPLETED and is at most 256 KiB. The fields below are inside that object, so you read the prose answer from result.final_text and the evidence from result.evidence.

Field	What it holds
`final_text`	The answer in prose.
`extracted`	The structured result, when you passed an `output_schema`.
`final_url`, `final_title`	Where the run ended.
`evidence.urls`	Every page it visited.
`evidence.side_effects`	Every action that changed something, with what the page showed afterwards.
`evidence.verifier`	What WOOL confirmed, and why. Also returned as `terminal.reason`.

On FAILED, result may still hold the evidence gathered before the run ended, which is often the fastest way to see what went wrong.

usage holds what the run cost once it is over: credits, and charged, which is false when the run wasn't billed because it failed on our side or never reached the browser. Billing has the rate card.

Ordering and pacing

Executions on one connection run one at a time, in the order you created them. Runs on different connections don't wait for each other. Requests to one website are paced across all of your executions, so a burst is queued rather than sent at once. That's why runs take from tens of seconds to a few minutes and why you poll.

What a run refuses

A run acts only as the connected account, on the connected website. It won't sign in or create accounts, won't answer CAPTCHAs or other human checks, and won't reach other sites or accounts. Prompts that ask for those fail with session_expired, needs_user, or blocked_policy, so your product can tell the user what's needed instead of retrying.

Next steps

Results and evidence explains what a completed run gives you. Polling and history covers reading runs from code.