Skip to main content
A run is a single execution of an automation. When you call any TinyFish Web Agent endpoint, you create a run that moves through a lifecycle from start to finish.

​
Run Lifecycle

Every run moves through these statuses:
Cancellation is only supported for runs created via /run-async, /run-batch, or /run-sse. Runs created via the synchronous /run endpoint cannot be cancelled because the request blocks until completion. Request/response shape and idempotency behavior: Runs Reference.
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 includes a streaming_url where you can watch the browser execute in real time — useful for debugging, demos, or showing users what’s happening behind the scenes. It’s available while the run is active; once the run reaches a terminal status, switch to video_url from the run object to access the recording instead.

​
Understanding COMPLETED Status

COMPLETED means the infrastructure worked, not that your goal succeeded.
Always check the result field: Goal succeeded:
Infrastructure worked, goal failed: The browser worked fine, but TinyFish Web Agent couldn’t achieve your goal.
A run’s error field covers the other case — when the infrastructure itself fails, error.category tells you how to react: SYSTEM_FAILURE is a TinyFish issue (retry after retry_after), AGENT_FAILURE means the input needs fixing, BILLING_FAILURE means the run was rejected at the billing check before it started — add money at agent.tinyfish.ai/wallet (minimum top-up $10), or add credits on a legacy account — and UNKNOWN should be treated as retryable. Full run object and error object field list: Runs Reference. Runs can also use vault credentials for authenticated automation. Pass use_vault: true and optionally credential_item_ids when creating a run to let TinyFish log into sites using your connected password manager.

​
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.

​
Handling Run Results

Use this pattern to handle both infrastructure failures and goal failures in your code.

Runs Reference

List, get, cancel, batch, and per-step screenshots/HTML — full schema

Endpoints

Choose sync, async, batch, or streaming

Agent Mode, Max Steps, and Max Duration

Default vs Strict mode, step and time limits

Error Codes

Handle errors gracefully

Vault Credentials

Use password manager credentials in runs