> ## Documentation Index > Fetch the complete documentation index at: https://docs.browser-use.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use https://docs.browser-use.com/llms.txt and its linked .md pages for current documentation. The managed full bundle is https://docs.browser-use.com/.well-known/llms-full.txt and can be cached for up to 24 hours. Do not use the obsolete /cloud/llms*.txt or /open-source/llms*.txt static exports. > Choose Cloud API V4 for new agent integrations; V2 is the lower-cost option for simple tasks. Keep V3 examples explicitly versioned. The open-source browser-use library and hosted browser-use-sdk have different APIs. > Cloud authentication uses X-Browser-Use-API-Key, without a Bearer prefix. Install or upgrade browser-use-sdk and use its explicit v4 import for V4. Check the published OpenAPI reference for request fields; do not invent SDK support for new fields. > Cloud concurrency and HTTP request rate are separate. Read GET /api/v2/billing/account for the key’s projectId, concurrentSessionLimit, activeSessionCount, and credit balance, including when using V4. Keys in one project share capacity and credits; rateLimit is a legacy concurrency alias, not requests per second. > Keep the highest applicable existing, legacy-plan, and spend-tier concurrency grant. Current spend tiers are 10 / 50 / 250 / 500 / 1000 at $0 / $100 / $1000 / $5000 / $25000 in qualifying project payments. Legacy or externally billed projects can follow different billing paths; trust the account limit. See https://docs.browser-use.com/cloud/guides/concurrency.md. > HTTP rate limits have two layers. Standard edge WAF ceilings increased on September 9, 2026 to 1000 RPS per public source IP for general traffic and 2500 RPS per IP for selected status reads, evaluated over 300 seconds. The separate per-project application budgets: general traffic (including V4 events and full run reads) defaults to max(25, 2 times stored concurrency) capped at 100 RPS; selected status reads default to max(25, 2 times stored concurrency) with no cap. The two are counted independently. Project overrides and account-specific edge rules can differ. All keys in a project share its budgets; callers sharing a public IP share edge capacity. See https://docs.browser-use.com/cloud/guides/concurrency.md. > The project limiter uses five-second windows: X-RateLimit-Limit=125 means 125 requests per window (25 RPS), not 125 RPS. Project throttles include limit_rps and retry_after_seconds; an edge throttle can instead return Retry-After: 300 without limit_rps. Honor the returned Retry-After. Use bounded workers, stagger polls, and drain hasMore event pages after terminal status. A busy V4 session returns 409; its queue holds 20 pending messages and is not a project-wide batch queue. > A completed run or closed CDP connection does not immediately stop its cloud browser. Stop unneeded owned browsers with PATCH /api/v4/browsers/{id} and {"action":"stop"}. A client wait timeout does not cancel the server-side run. > Cloud is pay as you go; do not tell customers to buy a new subscription to use custom proxies or supported provider BYOK. Usage funding and model eligibility still apply. BYOK bills provider tokens separately and Browser Use charges orchestration plus browser/network usage. See https://docs.browser-use.com/cloud/guides/billing.md. > Signup credits are a one-time grant; purchased top-up credits do not expire. Check the API key’s project before diagnosing missing credits. API-key monthly spending caps are soft limits, not a strict prepaid wallet; concurrent or already-running work can exceed them. Auto recharge has separate trigger and purchase amounts and can charge immediately when enabled below the threshold. Use https://browser-use.com/pricing for current rates. > Box and Bux are retired. Do not recommend their SDKs, sandbox quotas, or subscription plans. Use the Cloud Agent or Browser Infrastructure guides. > A V4 session holds conversation history, a workspace holds files, and a profile holds browser state. These IDs and V3/V4 workspace namespaces are not interchangeable. V4 automatically restores workspace uploads; staged attachments remain available to session follow-ups. Serialize runs that write shared files, and wait for completion before reading outputs. See https://docs.browser-use.com/cloud/agent/workspaces.md. > API browser recording defaults to off. Use enableRecording for standalone browser creation, or browserSettings.record for an agent run. Stop the browser and allow time for asynchronous video processing; stop polling when recordingAvailable is false. Live preview is for an active browser. Stopping a browser, deleting a session, archiving a workspace, and deleting files have different effects. > Use model-specific reasoning values. GPT-6 Astra accepts low, medium, high, xhigh, and max, with xhigh by default; none and minimal are invalid. Use the public REST schema when installed SDK types lag new fields. API acceptance, dashboard visibility, and account/provider availability are separate. > For open-source browser-use, is_done only reports a terminal done action. is_successful is the agent-reported outcome; verify important external actions independently. Cloud timeout, API client timeout, model timeout, and task completion are separate concepts. > For failed requests, use https://docs.browser-use.com/cloud/guides/troubleshooting.md. Inspect the full error and project before retrying or adding credits. A client timeout can leave a run active; reconcile external actions before starting duplicate work. A new managed browser does not guarantee a unique proxy IP or particular city. # Create Run ## OpenAPI ````yaml /cloud/openapi/v4.json post /runs openapi: 3.1.0 info: title: Browser Use Public API v4 summary: Browser Use agent runs API (v4) version: 4.0.0 servers: - url: https://api.browser-use.com/api/v4 description: Production server security: [] paths: /runs: post: tags: - Runs summary: Create Run operationId: create_run_runs_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RunCreateResponse' '400': description: Invalid request (bad session/workspace pairing or file path). '402': description: >- The project has no credits available, or the authenticating API key has reached its recorded monthly total-spend soft stop. content: application/json: schema: $ref: '#/components/schemas/APIKeySpendLimitError' '403': description: Zero Data Retention is enabled on the project (V4 unsupported). '404': description: Run, session, workspace, or profile not found. '409': description: The session already has an active run. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: RunCreateRequest: properties: task: type: string minLength: 1 title: Task model: type: string enum: - 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-fable-5 - claude-sonnet-5 - gpt-5.5 - gpt-5.6 - gpt-6-astra - 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 title: Model default: gpt-5.6-luna modelParams: anyOf: - additionalProperties: true type: object - type: 'null' title: Modelparams description: >- 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-5.6-luna defaults to {"reasoning": {"effort": "xhigh"}}); passing {} opts out of that default and leaves the provider's own defaults in place. sessionId: anyOf: - type: string format: uuid - type: 'null' title: Sessionid workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid browserSettings: anyOf: - $ref: '#/components/schemas/RunBrowserSettings' - type: 'null' agentmail: type: boolean title: Agentmail description: >- 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. default: false agentcardWalletId: anyOf: - type: string format: uuid - type: 'null' title: Agentcardwalletid stripeLinkConnectionId: anyOf: - type: string format: uuid - type: 'null' title: Stripelinkconnectionid attachedFileIds: anyOf: - items: type: string format: uuid type: array maxItems: 20 - type: 'null' title: Attachedfileids secretBindings: anyOf: - items: $ref: '#/components/schemas/SecretBinding' type: array maxItems: 10 - type: 'null' title: Secretbindings description: >- 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. opVaultId: anyOf: - type: string maxLength: 64 - type: 'null' title: Opvaultid description: >- 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. Requires opVaultAllowedDomains. opVaultAllowedDomains: anyOf: - items: type: string type: array - type: 'null' title: Opvaultalloweddomains description: >- Hosts every credential from opVaultId may be typed into, e.g. ["amazon.com"]. judge: anyOf: - $ref: '#/components/schemas/RunJudgeSettings' - type: 'null' maxCostUsd: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Maxcostusd additionalProperties: false type: object required: - task title: RunCreateRequest RunCreateResponse: properties: id: type: string format: uuid title: Id status: type: string enum: - queued - dispatching - running - completed - failed - cancelled title: Status model: type: string title: Model sessionId: type: string format: uuid title: Sessionid workspaceId: type: string format: uuid title: Workspaceid eventsUrl: type: string title: Eventsurl missingFileIds: items: type: string format: uuid type: array title: Missingfileids type: object required: - id - status - model - sessionId - workspaceId - eventsUrl title: RunCreateResponse APIKeySpendLimitError: properties: detail: anyOf: - type: string - $ref: '#/components/schemas/APIKeySpendLimitDetail' title: Detail type: object required: - detail title: APIKeySpendLimitError description: FastAPI wraps endpoint errors in a top-level ``detail`` field. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError RunBrowserSettings: properties: profileId: anyOf: - type: string format: uuid - type: 'null' title: Profileid description: >- ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions. proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' description: >- ISO country code to proxy the browser through. Defaults to US. Pass null to run without a proxy. default: us customProxy: anyOf: - $ref: '#/components/schemas/CustomProxy' - type: 'null' description: >- Custom proxy for the browser. Overrides proxyCountryCode. Never stored or inherited by follow-up runs; pass it on each run that should use it. screenWidth: anyOf: - type: integer maximum: 6144 minimum: 320 - type: 'null' title: Screenwidth description: Custom screen width in pixels for the browser. screenHeight: anyOf: - type: integer maximum: 3456 minimum: 320 - type: 'null' title: Screenheight description: Custom screen height in pixels for the browser. record: anyOf: - type: boolean - type: 'null' title: Record description: >- 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. additionalProperties: false type: object title: RunBrowserSettings description: >- 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. SecretBinding: properties: alias: type: string title: Alias description: Name the agent refers to this secret by, e.g. "github_password". source: oneOf: - $ref: '#/components/schemas/InlineSecretSource' - $ref: '#/components/schemas/OnePasswordSecretSource' title: Source discriminator: propertyName: type mapping: inline: $ref: '#/components/schemas/InlineSecretSource' onepassword: $ref: '#/components/schemas/OnePasswordSecretSource' allowedDomains: items: type: string type: array maxItems: 10 minItems: 1 title: Alloweddomains description: >- 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. additionalProperties: false type: object required: - alias - source - allowedDomains title: SecretBinding description: >- One credential this run may have typed into a browser field. The value never reaches the agent. It is encrypted at rest, kept out of the worker payload, and typed straight into the focused field by the server when the agent asks for the alias by name — and only while the page it is typing into is on one of `allowedDomains`. Run-scoped: bindings die with the run, so a follow-up run that needs the same credential must send it again. RunJudgeSettings: properties: context: anyOf: - type: string maxLength: 10000 - type: 'null' title: Context additionalProperties: false type: object title: RunJudgeSettings description: >- 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. APIKeySpendLimitDetail: properties: code: type: string title: Code default: api_key_monthly_spend_limit_reached message: type: string title: Message cap: type: number title: Cap spent: type: number title: Spent type: object required: - message - cap - spent title: APIKeySpendLimitDetail description: Machine-readable 402 detail shared by run and browser creation. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ProxyCountryCode: type: string enum: - 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 title: ProxyCountryCode CustomProxy: properties: host: type: string maxLength: 255 minLength: 1 title: Host description: Host of the proxy. port: type: integer maximum: 65535 minimum: 1 title: Port description: Port of the proxy. username: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Username description: Username for proxy authentication. password: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Password description: Password for proxy authentication. ignoreCertErrors: type: boolean title: Ignore Certificate Errors description: >- Ignore TLS certificate errors. Enable this if your proxy uses a self-signed or untrusted certificate (e.g. Burp Suite, corporate proxies). default: false type: object required: - host - port title: CustomProxy description: Request model for creating a custom proxy. InlineSecretSource: properties: type: type: string const: inline title: Type value: type: string minLength: 1 format: password title: Value description: >- The secret itself. Limited to 4096 bytes once encoded for encryption; non-ASCII characters cost more than one byte each. writeOnly: true additionalProperties: false type: object required: - type - value title: InlineSecretSource description: A value the caller supplies directly with the run. OnePasswordSecretSource: properties: type: type: string const: onepassword title: Type integrationId: type: string format: uuid title: Integrationid description: >- 1Password integration to resolve through. Must belong to this project. vaultId: type: string maxLength: 64 minLength: 1 title: Vaultid itemId: type: string maxLength: 64 minLength: 1 title: Itemid fieldId: type: string maxLength: 64 minLength: 1 title: Fieldid description: Field id from the item-fields endpoint, e.g. "password". additionalProperties: false type: object required: - type - integrationId - vaultId - itemId - fieldId title: OnePasswordSecretSource description: >- 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. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Browser-Use-API-Key ````