---
title: "Create Run"
method: POST
path: "/runs"
tags: ["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

- RunCreateRequest
  - `task` string, required
  - `outputSchema` object, 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.
  - `modelParams` object, 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.
  - `sessionId` string, uuid, nullable
  - `workspaceId` string, uuid, nullable
  - `browserSettings` RunBrowserSettings: Browser config, owned by the browser row (never the run). Follow-ups: omitted fields inherit the session's prior browser; explicit values apply only to newly provisioned browsers (a live browser is reused as-is). Profile is the exception: a different profile → 400; an explicit value mismatching the live browser's profile (incl. null vs a profiled browser) declines reuse and provisions fresh. A live browser already matching the requested profile is reused. Extensions are session-wide: follow-ups inherit them, and a different set → 400 (see extensionIds).
    - `profileId` string, uuid, nullable: ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions.
    - `proxyCountryCode` 'ad' | 'ae' | 'af' | 'ag' | 'ai' | 'al' | 'am' | 'an' | 'ao' | 'aq' | 'ar' | 'as' | 'at' | 'au' | 'aw' | 'az' | 'ba' | 'bb' | 'bd' | 'be' | 'bf' | 'bg' | 'bh' | 'bi' | 'bj' | 'bl' | 'bm' | 'bn' | 'bo' | 'bq' | 'br' | 'bs' | 'bt' | 'bv' | 'bw' | 'by' | 'bz' | 'ca' | 'cc' | 'cd' | 'cf' | 'cg' | 'ch' | 'ci' | 'ck' | 'cl' | 'cm' | 'co' | 'cr' | 'cs' | 'cu' | 'cv' | 'cw' | 'cx' | 'cy' | 'cz' | 'de' | 'dj' | 'dk' | 'dm' | 'do' | 'dz' | 'ec' | 'ee' | 'eg' | 'eh' | 'er' | 'es' | 'et' | 'fi' | 'fj' | 'fk' | 'fm' | 'fo' | 'fr' | 'ga' | 'gd' | 'ge' | 'gf' | 'gg' | 'gh' | 'gi' | 'gl' | 'gm' | 'gn' | 'gp' | 'gq' | 'gr' | 'gs' | 'gt' | 'gu' | 'gw' | 'gy' | 'hk' | 'hm' | 'hn' | 'hr' | 'ht' | 'hu' | 'id' | 'ie' | 'il' | 'im' | 'in' | 'iq' | 'ir' | 'is' | 'it' | 'je' | 'jm' | 'jo' | 'jp' | 'ke' | 'kg' | 'kh' | 'ki' | 'km' | 'kn' | 'kp' | 'kr' | 'kw' | 'ky' | 'kz' | 'la' | 'lb' | 'lc' | 'li' | 'lk' | 'lr' | 'ls' | 'lt' | 'lu' | 'lv' | 'ly' | 'ma' | 'mc' | 'md' | 'me' | 'mf' | 'mg' | 'mh' | 'mk' | 'ml' | 'mm' | 'mn' | 'mo' | 'mp' | 'mq' | 'mr' | 'ms' | 'mt' | 'mu' | 'mv' | 'mw' | 'mx' | 'my' | 'mz' | 'na' | 'nc' | 'ne' | 'nf' | 'ng' | 'ni' | 'nl' | 'no' | 'np' | 'nr' | 'nu' | 'nz' | 'om' | 'pa' | 'pe' | 'pf' | 'pg' | 'ph' | 'pk' | 'pl' | 'pm' | 'pn' | 'pr' | 'ps' | 'pt' | 'pw' | 'py' | 'qa' | 're' | 'ro' | 'rs' | 'ru' | 'rw' | 'sa' | 'sb' | 'sc' | 'sd' | 'se' | 'sg' | 'sh' | 'si' | 'sj' | 'sk' | 'sl' | 'sm' | 'sn' | 'so' | 'sr' | 'ss' | 'st' | 'sv' | 'sx' | 'sy' | 'sz' | 'tc' | 'td' | 'tf' | 'tg' | 'th' | 'tj' | 'tk' | 'tl' | 'tm' | 'tn' | 'to' | 'tr' | 'tt' | 'tv' | 'tw' | 'tz' | 'ua' | 'ug' | 'uk' | 'us' | 'uy' | 'uz' | 'va' | 'vc' | 've' | 'vg' | 'vi' | 'vn' | 'vu' | 'wf' | 'ws' | 'xk' | 'ye' | 'yt' | 'za' | 'zm' | 'zw'
    - `customProxy` CustomProxy: Request model for creating a custom proxy.
      - `host` string, required: Host of the proxy.
      - `port` integer, required: Port of the proxy.
      - `username` string, nullable: Username for proxy authentication.
      - `password` string, nullable: Password for proxy authentication.
      - `ignoreCertErrors` boolean: Ignore TLS certificate errors. Enable this if your proxy uses a self-signed or untrusted certificate (e.g. Burp Suite, corporate proxies).
    - `screenWidth` integer, nullable: Custom screen width in pixels for the browser.
    - `screenHeight` integer, nullable: Custom screen height in pixels for the browser.
    - `allowResizing` boolean, nullable: Let you or the agent resize the browser window over CDP. Resizing makes the browser easier to detect. API runs default to off. Follow-up runs inherit the value of the previous browser. The value applies only when the run starts a new browser.
    - `record` boolean, nullable: Record the browser session to an mp4, retrievable via GET /browsers/{id} once the browser stops. API runs default to off; pass true to enable. Like other browser settings, this only applies when a new browser is provisioned: a follow-up that reuses the session's live browser keeps that browser's recording state. Ignored (always off) for Zero Data Retention projects.
    - `extensionIds` string[]: Up to 3 ready extensions from POST /api/v4/extensions to install in every browser of the session. Follow-up runs inherit the session's extensions; passing a different set returns 400. After you delete an extension, omit extensionIds or pass the reduced set; later browsers skip deleted extensions. The agent is not told about installed extensions, so name any extension pages in the task.
  - `keepAlive` integer, 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.
  - `agentmail` boolean: 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.
  - `agentcardWalletId` string, uuid, nullable
  - `stripeLinkConnectionId` string, uuid, nullable
  - `agenticAutofillGrantId` string, uuid, nullable
  - `attachedFileIds` string[], nullable
  - `secretBindings` SecretBinding[], nullable: Credentials this run may use without ever seeing them. The agent can ask the server to type a binding by alias on one of its allowed domains; it cannot read the value. Bindings are not persisted past the run.
    - `alias` string, required: Name the agent refers to this secret by, e.g. "github_password".
    - `source` union, required
      - InlineSecretSource: A value the caller supplies directly with the run.
        - `type` 'inline', required
        - `value` string, password, required: The secret itself. Limited to 4096 bytes once encoded for encryption; non-ASCII characters cost more than one byte each.
      - OnePasswordSecretSource: One field of a 1Password item, resolved only when the agent asks for it. Nothing here is a secret: the quadruple NAMES a credential without carrying it. Creating the binding makes no call to 1Password — a provider outage must not stop a run from being dispatched, and no vault is ever enumerated. A one-time-password field resolves to its current code; its seed is never read, so there is no flag to ask for one.
        - `type` 'onepassword', required
        - `integrationId` string, uuid, required: 1Password integration to resolve through. Must belong to this project.
        - `vaultId` string, required
        - `itemId` string, required
        - `fieldId` string, required: Field id from the item-fields endpoint, e.g. "password".
    - `allowedDomains` string[], required: Hosts the secret may be typed into, e.g. ["github.com"]. A host covers its subdomains. Bare hostnames only — no scheme, port, path, or wildcard.
  - `opVaultId` string, 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.
  - `opVaultAllowedDomains` string[], 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.
  - `judge` RunJudgeSettings: Opt-in LLM judgement of the finished run. Presence of this object turns the judge on (send {} for defaults); CP judges the run's trajectory after it goes terminal and surfaces the verdict as RunSummary.judgement (null until it lands). The judge's LLM call is billed to the run.
    - `context` string, nullable
  - `maxCostUsd` union
    - number
    - string

## Response `200`

Successful Response

- RunCreateResponse
  - `id` string, uuid, required
  - `status` 'queued' | 'dispatching' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `model` string, required
  - `sessionId` string, uuid, required
  - `workspaceId` string, uuid, required
  - `eventsUrl` string, required
  - `missingFileIds` string[]
  - `skippedVaultItems` string[]: 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.

## Other responses

- `400`: Invalid request (bad session/workspace pairing or file path).
- `402`: The project has no credits available, or the authenticating API key has reached its recorded monthly total-spend soft stop.
- `403`: Zero Data Retention is enabled on the project (V4 unsupported).
- `404`: Run, session, workspace, or profile not found.
- `409`: The session already has an active run.
- `422`: Validation Error
- `429`: The project is at its concurrent-session limit.

---

[API](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4.md) · [All operations](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/llms.txt) · [OpenAPI document](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/revisions/cd7b1eee1102?raw)