> ## 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. This did not raise the separate per-project application budgets: general traffic defaults to 25 RPS, including V4 events and full run reads; selected status reads default to max(25, 2 times stored concurrency). 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. # Concurrency and limits > Preserved legacy allowances, spend tiers, browser lifetime, polling budgets, queues, and retry guidance. Browser Use has separate limits for simultaneous browser work and API request frequency. A project can have available browser capacity and still receive a rate-limit response if it sends too many HTTP requests. For reliable batch processing, use a bounded worker pool, track the browsers your application owns, and budget polling requests across the project. ## Check your project's capacity Use your API key to inspect its project: ```bash theme={null} curl --fail-with-body \ https://api.browser-use.com/api/v2/billing/account \ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" ``` This billing endpoint is also useful when your application uses V4 runs. Read: | Field | Meaning | | ------------------------ | ------------------------------------------------------------------------------------------------- | | `projectId` | The project this API key accesses. Check this if you funded a different project in the dashboard. | | `apiKeyId` | The internal identifier of the authenticated key. | | `concurrentSessionLimit` | The project's current browser concurrency allowance. | | `activeSessionCount` | Reported active browser count. Track the browser IDs your application owns as well. | | `totalCreditsBalanceUsd` | Its reported available credit balance. | `rateLimit` is a legacy concurrency field. It does not tell you the HTTP request limit. Treat account information as a snapshot rather than a reservation for a future request. Several workers may read the same available capacity before any of them starts a browser. Keys in the same project share its capacity and balance. Creating more keys does not create more browser slots. Free accounts can also have limits across their projects. ## How usage tiers work For projects on current pricing, concurrency increases with the project's net settled lifetime Stripe payments: | Lifetime qualifying spend | Concurrent sessions | | ------------------------: | ------------------: | | \$0 | 10 | | \$100 | 50 | | \$1,000 | 250 | | \$5,000 | 500 | | \$25,000 | 1,000 | Payments count for the project that received them. Refunds and disputed payments do not contribute to qualifying spend. Signup credits and other credit grants are not qualifying purchases. Funding through other billing arrangements may follow different rules. **Your higher concurrency allowance is preserved.** When a project participates in spend tiers, its limit takes the maximum of its applicable legacy-plan allowance, the current pricing floor, and its spend-tier allowance. An already-granted higher limit is not automatically lowered. For example, a legacy allowance of 250 remains 250 when the spend tier would grant 50. Some active legacy or externally billed projects follow a different billing path. Lapsed or cancelling legacy plans can transition onto current pricing while keeping their higher grant. Use `concurrentSessionLimit` and the project’s Billing page as the source of truth. If the tier ladder is absent or differs from your expectations, contact support with your project ID before making a purchase solely to increase concurrency. ## Keep track of browser lifetime A V4 **session** is a conversation. A **run** is one turn in that conversation. A **browser** is the live Chrome instance used for website interaction. A browser can survive the run that created it and be reused by a later turn. A conversation can also have multiple browsers. Additional tabs in the same browser are not additional browser sessions. After all runs in a conversation are inactive, V4 browsers become eligible for cleanup after approximately 20 minutes without recent run activity. Cleanup runs periodically, so this is not an exact shutdown deadline. V4 agent browsers also have a four-hour hard timeout. If your application is finished with a browser, explicitly stop that browser rather than relying on idle cleanup. Only stop browser IDs your application owns and no longer needs. For a standalone browser, the stop request is: ```bash theme={null} curl --fail-with-body -X PATCH \ "https://api.browser-use.com/api/v4/browsers/$BROWSER_SESSION_ID" \ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"stop"}' ``` Do not use this against a browser another active run or person still needs. Closing your local CDP connection is not a substitute for checking the cloud browser's lifecycle. If your workflow requires human interaction, deliver the live-view URL from `browser.ready` while the run/browser is active. A conversation remaining in history does not mean its live browser is still available. ## Queue follow-ups within a conversation Only one V4 run can be active in a session. Submitting a direct follow-up while it is busy returns **409**. Choose the behavior you need: * Wait for the active run to finish, then submit the next turn. * Submit through the session message queue to process a later turn. * Intentionally interrupt the active run when you want to change its current work. The session message queue accepts up to **20 pending messages**. A full queue returns **429**. It is a queue for that conversation, not a project-wide batch queue or a reservation of browser capacity. Keep a large batch in your application's own job queue. Admit a bounded number of jobs and leave the rest pending there. ## Budget HTTP requests separately HTTP traffic passes through two separate limits: a shared per-IP edge limit and your project's application limit. Raising one does not raise the other. ### Edge limits On September 9, 2026, the standard edge (WAF) ceilings increased: | Requests from one public source IP | Edge ceiling | Evaluation window | | ---------------------------------- | --------------------: | --------------------------------: | | General API traffic | 1,000 requests/second | 300,000 requests over 300 seconds | | Selected individual status reads | 2,500 requests/second | 750,000 requests over 300 seconds | These are approximate rates evaluated over a five-minute window, not a strict per-second cap or a guaranteed burst allowance. Applications behind the same NAT or proxy share the IP's budget. Account-specific edge rules and certain special endpoints can have different limits. ### Project limits The edge increase did **not** change the standard per-project application buckets: | Requests | Default request budget | | ----------------------------------------------------------------- | ------------------------------------------------: | | Creates, lists, updates, deletes, event reads, and full run reads | 25 requests/second | | Selected individual status reads | `max(25, 2 × stored concurrency)` requests/second | The selected V4 polling endpoints include: * `GET /api/v4/runs/{run_id}/status` * `GET /api/v4/sessions/{session_id}` * `GET /api/v4/browsers/{browser_session_id}` `GET /api/v4/runs/{run_id}/events` and `GET /api/v4/runs/{run_id}` use the general bucket. Their budget does not automatically grow with your concurrency grant. Account overrides and other protections can differ from these defaults; use the response headers and error details when diagnosing throttling. For example, a project with 500 stored concurrent sessions and no request-rate override has a 1,000 RPS status-polling budget and a separate 25 RPS general budget. All API keys in that project share those budgets. Creating a new key does not create more request capacity. The project limiter counts requests in **five-second windows**. A 25 RPS budget therefore permits 125 requests per window. `X-RateLimit-Limit` reports that window allowance, not requests per second: a value of `125` does not mean 125 RPS. `X-RateLimit-Remaining` is the window's remaining request count. `X-RateLimit-Reset` is a relative number of seconds, not a Unix timestamp. A project throttle includes `limit_rps` and `retry_after_seconds` in the JSON body and normally sends `Retry-After: 5`. An edge throttle can instead send `Retry-After: 300` without `limit_rps`. Honor the delay actually returned; a five-second retry loop is inappropriate for a five-minute edge throttle. Capture the response headers and body when asking support to identify which limit applied. A missing limit header is not a promise of unlimited traffic. If you only need the final result, use the SDK's status-based wait helper: ```python theme={null} from browser_use_sdk.v4 import BrowserUse client = BrowserUse() # run_id is the ID of a run your application already created. result = client.runs.wait_for_completion(run_id) print(result.status, result.result) ``` SDK 3.11.3 defaults to a two-second status interval and a four-hour client wait timeout. Reaching that timeout raises an exception locally; it does not cancel the server-side run. Inspect or cancel the existing run before deciding whether to submit replacement work. ### When you need events Use the returned cursor to continue reading and process every page with `hasMore` before treating the event stream as caught up. After terminal status, drain the remaining event pages; do not exit solely because a separate status request completed. Set a request budget across all event streams in the project. For example, polling events once per second for 50 runs would generate about 50 event requests per second, exceeding the standard general bucket before counting any creates or other requests. Polling each every five seconds would average about 10 event requests per second; pagination and other traffic still need headroom. Spread poll times so that every worker does not send its request on the same clock tick. A per-project limiter in your application is more predictable than each worker independently retrying. For SDK event waits, set `wait_for_event(..., interval=3)` in Python or `waitForEvent(..., { interval: 3_000 })` in TypeScript. This also works on SDK 3.11.3, whose event-wait default is one second. One hundred waits at a three-second interval average about 33 event requests per second, exceeding the standard 25 RPS general budget. For that workload, explicitly use a five-second interval (20 event requests per second) or a shared request scheduler, leaving headroom for creates, pagination, and other general calls. The event-wait helper pauses between pages too. For an old run with a large event history, start from a known cursor or implement paginated reads within your shared request budget; a longer interval also makes backlog traversal slower. ## Diagnose errors before retrying | Response | Likely meaning | What to do | | ------------------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | 429 with `error: "rate_limited"` and `limit_rps` | Project HTTP request budget exhausted | Honor `Retry-After`/`retry_after_seconds`; reduce or stagger requests across the project. | | 429 with `error: "rate_limited"`, no `limit_rps`, and `Retry-After: 300` | Edge request protection | Back off for the returned delay; check bursts and traffic sharing the same public IP. | | 429 with a concurrent-session message in `detail` | Active session allowance reached | Inspect capacity, stop unneeded browsers, and reduce admitted jobs. | | 429 with a queue-full message in `detail` | This conversation has 20 pending messages | Wait for its queue to drain or cancel an appropriate pending message. | | 409 with an active-run message | Conversation is already busy | Wait, queue, or intentionally interrupt. | | 402 with `detail.code: "api_key_monthly_spend_limit_reached"` | This key's monthly soft spending cap was reached | Check the cap and recorded spend in the current UTC month. | | Other 402 | May be insufficient project balance or another payment condition | Inspect the complete response and the API key's project. | The SDK retries some transient responses, including 429, but the default is only three retries. SDK 3.11.3 uses exponential delays of roughly 1, 2, and 4 seconds and does not itself apply `Retry-After` or jitter. Add application-level scheduling for sustained workloads. Do not repeatedly submit a new billable run when the outcome of an earlier submission is uncertain. SDK 3.11.3 errors expose the response status and body, but not response headers. Use `retry_after_seconds` when the body includes it. To diagnose an edge throttle or read its exact `Retry-After`, capture the raw HTTP response through your application's HTTP instrumentation or a REST client. API-key monthly spending caps are **soft limits**. They use a cached spend snapshot; already-running or simultaneous work can finish above the cap. They do not replace project balance management or per-run cost controls. BYOK provider charges also remain separate from Browser Use charges. ## A practical batch-processing pattern 1. Resolve the key's project, available balance, and current capacity. 2. Keep jobs in a durable application queue and admit a bounded number of workers. Leave room for browsers used elsewhere in the project and additional browsers created by agents. 3. Track job ID, session ID, run ID, and browser IDs separately. 4. Use cheap status polling for result-only jobs; share one request budget across event streams and general API operations. 5. Handle busy-session, queue, rate, capacity, and spending errors according to their cause. 6. Record terminal outcomes, release unneeded browsers, and retry only when the job's previous outcome is understood. When contacting support, include the UTC time window, endpoint, status code, redacted response body, project ID, SDK version, run/session/browser IDs, and approximate request rate and concurrency. Do not send API keys, proxy passwords, or saved browser credentials. See also [Billing and credits](/cloud/guides/billing), [Sessions](/cloud/agent/sessions), and [Observability](/cloud/agent/observability).