> ## 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.
# Thinking levels
> Configure model reasoning depth across API V2, V3, and V4.
Browser Use exposes reasoning controls in two forms:
* **API V4** uses provider-native values inside `modelParams`.
* **API V3 and V2** use the provider-neutral `thinkingLevel` field with
`disabled`, `low`, `medium`, or `high`.
See [Models](/cloud/agent/models) for the complete V4 model list, recommended
model, token pricing, and BYOK routes.
## API V4 model parameters
V4 forwards an allow-listed `modelParams` object to the selected provider. The
field names and accepted values therefore differ by model family.
| Model strings | Path | Accepted values |
| ------------------------------------------------------------------------ | ------------------------------ | ----------------------------------------------- |
| `gpt-6-astra` | `reasoning.effort` | `low`, `medium`, `high`, `xhigh`, `max` |
| `gpt-5.5` | `reasoning.effort` | `none`, `low`, `medium`, `high`, `xhigh` |
| `gpt-5.6`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | `reasoning.effort` | `none`, `low`, `medium`, `high`, `xhigh`, `max` |
| `claude-opus-4.7`, `claude-opus-4.8`, `claude-opus-5`, `claude-sonnet-5` | `output_config.effort` | `low`, `medium`, `high`, `xhigh`, `max` |
| Same Claude models | `thinking.type` | `adaptive`, `disabled` |
| Same Claude models | `thinking.display` | `omitted`, `summarized` |
| `gemini-3-flash`, `gemini-3.5-flash`, `gemini-3.6-flash` | `thinkingConfig.thinkingLevel` | `minimal`, `low`, `medium`, `high` |
| `gemini-3.1-pro` | `thinkingConfig.thinkingLevel` | `low`, `medium`, `high` |
`glm-5.2`, `glm-5.3-flash`, `grok-4.5`, `grok-4.6`,
`deepseek-v4-flash-vision`, `kimi-k3`, `minimax-m3`, and `claude-fable-5`
do not currently accept V4 `modelParams`.
Omitting `modelParams` applies Browser Use's defaults for that V4 model. For
example, `gpt-5.6-luna` and `gpt-6-astra` default to `reasoning.effort: xhigh`.
Astra does not accept `none` or `minimal`. Send an empty
object (`"modelParams": {}`) to opt out and use the provider's defaults.
### V4 examples
```bash OpenAI theme={null}
curl -X POST https://api.browser-use.com/api/v4/runs \
-H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Compare three project-management tools",
"model": "gpt-5.6-luna",
"modelParams": {"reasoning": {"effort": "high"}}
}'
```
```bash Anthropic theme={null}
curl -X POST https://api.browser-use.com/api/v4/runs \
-H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Compare three project-management tools",
"model": "claude-opus-5",
"modelParams": {"output_config": {"effort": "high"}}
}'
```
```bash Google theme={null}
curl -X POST https://api.browser-use.com/api/v4/runs \
-H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Compare three project-management tools",
"model": "gemini-3.6-flash",
"modelParams": {"thinkingConfig": {"thinkingLevel": "high"}}
}'
```
## API V3 support
V3 accepts the normalized REST field `thinkingLevel`. Legacy aliases are
normalized before validation: `bu-mini` maps to `gemini-3-flash`, `bu-max`
maps to `claude-sonnet-5`, and `bu-ultra` maps to `claude-opus-4.6`.
| Model strings | `disabled` | `low` | `medium` | `high` |
| ----------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :---: | :------: | :----: |
| `bu-mini`, `gemini-3-flash`, `gemini-3.5-flash` | Yes | Yes | Yes | Yes |
| `bu-max`, `bu-ultra`, `claude-sonnet-4.6`, `claude-opus-4.6`, `claude-opus-4.7`, `claude-sonnet-5`, `claude-opus-4.8`, `claude-haiku-4.5` | Yes | Yes | Yes | Yes |
| `gpt-5.2`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | Yes | Yes | Yes | Yes |
| `gpt-5-mini` | — | Yes | Yes | Yes |
| `gemini-3-pro`, `gemini-3.1-pro` | — | Yes | — | Yes |
| `glm-5.2` | Yes | — | — | Yes |
| `minimax-m3` | — | — | — | — |
For a follow-up task sent to an existing V3 session:
* Omit `thinkingLevel` to retain the session's current setting.
* Send a supported value to update the setting for the next task and later
follow-ups.
* Send `"thinkingLevel": null` to clear it and return to provider defaults.
The requested value is validated against the existing session's model, not
the request model default.
## API V2 support
V2 also accepts the normalized REST field `thinkingLevel`, but it has two
additional limitations. It cannot configure GLM thinking, and it cannot enable
fixed-budget thinking on older Claude 4/4.5 models because the legacy worker
cannot safely replay their thinking blocks. Those Claude models still accept
`disabled`.
| Model strings | `disabled` | `low` | `medium` | `high` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :---: | :------: | :----: |
| `browser-use-llm`, `browser-use-2.0`, `gemini-2.5-flash`, `gemini-3-flash-preview`, `gemini-3.5-flash`, `gemini-flash-latest`, `gemini-flash-lite-latest` | Yes | Yes | Yes | Yes |
| `gemini-2.5-pro` | — | Yes | Yes | Yes |
| `gemini-3-pro-preview`, `gemini-3.1-pro-preview` | — | Yes | — | Yes |
| `o3`, `o4-mini` | — | Yes | Yes | Yes |
| `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | Yes | Yes | Yes | Yes |
| `claude-sonnet-5`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5` | Yes | Yes | Yes | Yes |
| `claude-sonnet-4-20250514`, `claude-sonnet-4-5-20250929`, `claude-opus-4-5-20251101` | Yes | — | — | — |
| `gpt-4.1`, `gpt-4.1-mini`, `glm-5.2`, `minimax-m3`, `llama-4-maverick-17b-128e-instruct`, `claude-3-7-sonnet-20250219` | — | — | — | — |
V2's existing `thinking` boolean controls legacy agent behavior. It does not
select a provider reasoning depth and does not replace `thinkingLevel`.
## Provider mappings for V2 and V3
Browser Use validates the normalized V2/V3 value before dispatch, then maps it
to the provider's native control.
| Provider/model family | Mapping |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gemini 3 Flash | `disabled` becomes provider level `minimal`; `low`, `medium`, and `high` map directly. |
| Gemini 3.1 Pro | Supports only provider levels `low` and `high`. Legacy Gemini 3 Pro names route here. |
| Gemini 2.5 | Uses thinking budgets of 0, 1,024, 4,096, and 8,192 tokens. Gemini 2.5 Pro cannot use the zero-token budget. |
| Claude 4.6+ and Claude 5 | V3 uses adaptive thinking with the requested effort. V2 sends the effort without replaying thinking blocks. `disabled` turns thinking off where supported. |
| Earlier supported Claude 4/4.5 | Uses fixed budgets of 1,024, 4,096, and 8,192 tokens. V2 cannot enable these fixed-budget modes. |
| GPT-5.1+ | `disabled` becomes OpenAI reasoning effort `none`; the other levels map directly. |
| Earlier GPT-5, o3, and o4 | Supports `low`, `medium`, and `high`, but not `disabled`. |
| GLM | Exposes only a switch: `disabled` turns thinking off and `high` turns it on. V2 does not support the switch. |
## BYOK behavior
* **V2:** `thinkingLevel` uses the existing model route. It does not add a
per-request BYOK switch.
* **V3:** set `useOwnKey: true` for models that require a provider key. Native
and BYOK routes use the same support matrix.
* **V4:** add an Anthropic, OpenAI, or Google key under **Settings → API Keys →
Bring Your Own Key**. V4 automatically uses a matching key; there is no
request flag. `modelParams` works the same with Browser Use-managed and
customer-managed keys.
## V2 and V3 examples
REST JSON uses the camelCase wire field `thinkingLevel` in both API versions.
```bash API V3 theme={null}
curl -X POST https://api.browser-use.com/api/v3/sessions \
-H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Compare three project-management tools",
"model": "claude-opus-4.7",
"thinkingLevel": "high"
}'
```
```bash API V2 theme={null}
curl -X POST https://api.browser-use.com/api/v2/tasks \
-H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Compare three project-management tools",
"llm": "browser-use-2.0",
"thinkingLevel": "high"
}'
```
## Validation errors
Unsupported V2/V3 model-level pairs return HTTP 422. The request field is
camelCase, while the validation detail currently names the backend field in
snake\_case:
```text theme={null}
Model "gemini-3.1-pro" (provider "google") does not support thinking_level="medium". Supported values: low, high
```
V4 validates the provider-native path and uses its wire name in the error:
```text theme={null}
Model "gemini-3.1-pro" does not support modelParams.thinkingConfig.thinkingLevel='minimal'. Supported values: high, low, medium
```
## Compatibility and API references
The normalized V2/V3 field is optional and nullable. New sessions use provider
defaults until a level is supplied. Existing V3 sessions retain their current
setting when the field is omitted; send `null` to clear it. The current Python
and TypeScript SDKs expose the V2/V3 and V4 reasoning fields in their request
types and client methods.
Generated V4 `modelParams` schema.
Generated V3 `thinkingLevel` schema.
Generated V2 `thinkingLevel` schema.