> ## 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 / $200 / $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.
> Budget polling across the project: the standard general bucket is 25 requests/second, including V4 event reads and full run reads. Selected status reads have a separate higher bucket. Use bounded workers, stagger polls, respect Retry-After, and drain hasMore event pages after terminal status. A busy V4 session returns 409; its queue holds 10 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 |
|                     \$200 |                  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 **10 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

The standard per-project request buckets are:

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

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.

## Diagnose errors before retrying

| Response                                                      | Likely meaning                                                   | What to do                                                             |
| ------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 429 with `error: "rate_limited"`                              | HTTP request budget exhausted                                    | Honor `Retry-After`/`retry_after_seconds`; reduce or stagger requests. |
| 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 10 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.

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