Runs

Create Run

post/runs

Request

  • Base URL: https://api.browser-use.com/api/v4
  • URL: https://api.browser-use.com/api/v4/runs
  • Auth: API key in header X-Browser-Use-API-Key

Request body

taskstring required
outputSchemaobject nullable

Optional JSON Schema for the final output (API runs only).

model'mimo-v2.6-pro' | 'mimo-v2.6-flash' | 'deepseek-v4.1-flash' | 'glm-5.2' | 'grok-4.5' | 'grok-4.6' | 'glm-5.3-flash' | 'deepseek-v4-flash-vision' | 'kimi-k3' | 'minimax-m3' | 'claude-opus-4.7' | 'claude-opus-4.8' | 'claude-opus-5' | 'claude-opus-5-5' | 'claude-fable-5' | 'claude-sonnet-5' | 'claude-sonnet-5-5' | 'gpt-5.5' | 'gpt-5.6' | 'gpt-6-astra' | 'gpt-6-sol' | 'gpt-6.1-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gemini-3.6-flash' | 'gemini-3.5-flash' | 'gemini-3.1-pro' | 'gemini-3-flash' | 'bu-ultrafast' | 'bu-fast'

bu-ultrafast and bu-fast are early-access ultrafast presets; they take no modelParams and are rejected for projects without access.

modelParamsobject nullable

Optional provider-native request parameters for the selected model, written with the provider's own field names and values and forwarded unchanged (e.g. {"reasoning": {"effort": "high"}} for OpenAI, {"thinking": {"type": "adaptive"}} for Anthropic, {"thinkingConfig": {"thinkingLevel": "high"}} for Google). Supported paths and values are per-model; an unsupported path, value, or a model that accepts no parameters at all is rejected with 422. Omitting this field applies the model's default parameters (gpt-6-luna defaults to {"reasoning": {"effort": "high"}}); passing {} opts out of that default and leaves the provider's own defaults in place.

sessionIdstring uuid nullable
workspaceIdstring uuid nullable
keepAliveinteger nullable

Seconds the session's browser stays open after its last run, so a follow-up run reuses the same page, never past the browser's 4 h lifetime. Default 120. Follow-up runs inherit the session's value; send a new value to change it or null to restore the default. Kept time is billed as browser time. Ignored (always 120) for free-tier and Zero Data Retention projects.

agentmailboolean

If true, provisions a persistent temporary email inbox (via AgentMail) for the run workspace. The agent receives the email address in its context and can send, receive, read, and reply to email. Set false to disable AgentMail for this run.

agentcardWalletIdstring uuid nullable
stripeLinkConnectionIdstring uuid nullable
agenticAutofillGrantIdstring uuid nullable
attachedFileIdsstring[] nullable
opVaultIdstring nullable

A 1Password vault id whose items become typed secrets for this run. The project's connected 1Password integration is resolved server-side; no per-item ids are needed.

opVaultAllowedDomainsstring[] nullable

Hosts every credential from opVaultId may be typed into, e.g. ["amazon.com"]. Omit to derive each item's hosts from its own 1Password website entries; items with no website are then skipped and reported in skippedVaultItems. A host covers its subdomains, so 1Password's ExactDomain autofill setting is not honored either way.

Response

Successful Response

idstring uuid required
status'queued' | 'dispatching' | 'running' | 'completed' | 'failed' | 'cancelled' required
modelstring required
sessionIdstring uuid required
workspaceIdstring uuid required
eventsUrlstring required
missingFileIdsstring[]
skippedVaultItemsstring[]

Titles of opVaultId items that hold a credential but no 1Password website, so deriving their domains left them with nowhere to be typed. The run still starts without them; add a website to the item or pass opVaultAllowedDomains.

Changes

No recorded changes to this operation across all 1 revision of this API.