> ## 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
> Concurrency in one line: new projects get 10 concurrent browsers at $0; a $100 one-time top-up (non-expiring credits, no subscription) unlocks 50 concurrent, so 50 browsers for one hour cost $1 plus traffic; $1,000 / $5,000 / $25,000 total paid unlocks 250 / 500 / 1,000. Details below and at https://docs.browser-use.com/cloud/guides/concurrency.md.
> 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; V3 trades accuracy for speed and lower cost than V4; V2 is legacy and only for existing integrations. Keep V3 examples explicitly versioned. The open-source browser-use library and hosted browser-use-sdk have different APIs.
> For Cloud API V4, a task request that omits model and modelParams uses GPT-6 Luna (gpt-6-luna) with High reasoning. Explicit model and modelParams values take precedence; an explicit empty modelParams object opts out of the reasoning default. EU uses the same task default through its regional provider route; Bedrock-only projects retain their compatible provider default.
> 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 V4 agent browser stays open about 2 minutes after its session's last run activity, then stops automatically; a later follow-up gets a fresh browser (same settings and profile, no tabs). Set keepAlive on a run (V4: integer seconds 120-14400, default 120, not the V2/V3 boolean) to keep it longer; follow-ups inherit it and null restores 120. Free-tier and ZDR runs always use 120. Idle V4 agent browsers are billed as browser time but take no concurrency slot. A follow-up that reuses the open browser emits browser.reattached instead of browser.ready. Closing CDP does not stop a 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.
> V4 secretBindings.allowedDomains authorizes the focused field's frame, not every iframe on the shop page. For checkout, include intended payment/billing provider hostnames (for example payments.bigcommerce.com). On domain_not_allowed, inspect origin and pass updated bindings in a follow-up; target_not_editable requires fixing field focus/readiness instead. See https://docs.browser-use.com/cloud/guides/secrets.md.
> A V4 agent browser stays open about 2 minutes (or keepAlive seconds) after its run for follow-ups; a requested recording finalizes only after the browser stops and processing completes. Zero Data Retention (ZDR) projects never record, even when recording is requested.
> If you hit an issue you cannot explain, email contact@browser-use.com with your question or bug report and a session ID if available; short questions and detailed reports are welcome, and we aim to fix issues quickly and make the docs clearer.
# OpenAI browser automation with Browser Use
> Run OpenAI browser tools on Browser Use Cloud infrastructure. Enable clicks, typing, JavaScript, file transfers, and Bash with the Python SDK.
Connect OpenAI's browser tools to Browser Use Cloud with the Browser Use library.
OpenAI's SDK runs the model loop. Our driver turns tool calls into browser actions.
Browser Use Cloud runs Chromium remotely, so your application needs no local browser installation.
Use this driver for all 28 browser tools. Bash runs beside your application; the browser runs in Browser Use Cloud.
Use the [OpenAI + Playwright guide](https://docs.browser-use.com/cloud/tutorials/integrations/openai.md) for an existing Playwright application.
## Run your first task
You need [uv](https://docs.astral.sh/uv/getting-started/installation/), a Browser Use API key, and an OpenAI API key.
Choose an OpenAI model that supports Responses function tools.
**1. Create a project**
```bash theme={"theme":"css-variables"}
mkdir openai-browser-use
cd openai-browser-use
uv init --bare --python 3.12
uv add "browser-use[openai-tools] @ git+https://github.com/browser-use/browser-use.git@aadf9ecd91622be3ffefbca7ed626f329a4f2a3b"
```
This command installs this driver commit with all 28 browser tools and Bash.
Cloud browsers need no local Chromium installation.
**2. Set your API keys**
Get your [Browser Use key](https://cloud.browser-use.com/new-api-key) and [OpenAI key](https://platform.openai.com/api-keys).
```bash theme={"theme":"css-variables"}
export BROWSER_USE_API_KEY="your-browser-use-key"
export OPENAI_API_KEY="your-openai-key"
export OPENAI_MODEL="your-model"
```
**3. Download and run**
```bash theme={"theme":"css-variables"}
curl -fsSL https://raw.githubusercontent.com/browser-use/sdk/2d063e4e57c397bf95dca0404076fb2ff9eb34d3/examples/openai/browser_use_library.py -o browser_use_library.py
uv run python browser_use_library.py
```
The model follows a link and writes a source-backed summary with Bash.
The driver stops its remote browser when the script finishes.
The example enables OpenAI's [native compaction](https://developers.openai.com/api/docs/guides/compaction) at 60,000 tokens.
Compaction reduces conversation context during long tasks.
The SDK keeps control of the model loop.
## The complete example
The example enables all 28 browser tools and Bash.
```python browser_use_library.py theme={"theme":"css-variables"}
import asyncio
import os
from pathlib import Path
from urllib.parse import urlsplit
from browser_use.integrations.openai import Bash, BrowserUse
from openai import AsyncOpenAI
from openai.lib.browser import BROWSER_MEMBERS, AsyncBrowserToolset
from openai.lib.responses_tool_runner import AsyncResponsesToolRunner
async def confirm(context):
return True
async def allow_url(context, url):
parsed = urlsplit(url)
return parsed.scheme in {"http", "https"} and not parsed.username and not parsed.password
async def main():
model = os.environ["OPENAI_MODEL"]
async with AsyncOpenAI(timeout=180, max_retries=5) as client, BrowserUse(use_cloud=True) as driver:
tools = AsyncBrowserToolset(
driver,
members=BROWSER_MEMBERS,
confirm=confirm,
url_policy=allow_url,
)
runner = AsyncResponsesToolRunner(browser=tools, functions=[Bash(output_dir=Path("outputs"))])
try:
response = await runner.run(
client,
{
"model": model,
"store": False,
"context_management": [{"type": "compaction", "compact_threshold": 60000}],
"input": "Open https://example.com, follow Learn more, and save a source-backed summary in summary.md using Bash.",
},
max_steps=100,
)
print(response.output_text)
finally:
runner.close()
tools.close()
asyncio.run(main())
```
The confirmation callback approves browser actions in this example.
Use it only in an isolated environment for tasks you authorize.
Bash runs on your application host, not inside the remote browser.
Bash uses your application's Python environment and stores temporary files under outputs/.tmp.
Pass python\_executable to select another Python environment.
It uses a stripped environment and execution limits, but it does not provide a security sandbox.
## Browser actions
The driver uses the same Browser Use Actor API as our Claude integration.
| Task | Tools |
| - | - |
| Move between pages | `navigate` |
| Manage tabs | `new_tab`, `list_tabs`, `switch_tab`, `close_tab` |
| Read a page | `read_page`, `get_page_text`, `find`, `screenshot` |
| Interact with elements | `click`, `hover`, `type`, `key`, `scroll`, `scroll_to`, `select_option` |
| Inspect and wait | `zoom`, `wait_for`, `read_page_scoped`, `read_diagnostics` |
| Use coordinates | `click_at`, `hover_at`, `drag_path`, `hold_keys` |
| Change controls | `set_checked` |
| Run page JavaScript | `run_script` |
| Transfer approved files | `upload_file`, `download_file` |
| Run shell commands | `Bash` on your application host |
OpenAI's SDK provides `list_tabs` from the driver's state.
Use `members=BROWSER_MEMBERS` to expose all 28 browser tools.
Update your confirmation callback to permit the actions your task needs.
File tools move one file per grant that your application issues.
> **Coordinate actions and JavaScript**
>
> Enable every browser tool with `members=BROWSER_MEMBERS`:
>
> ```python theme={"theme":"css-variables"}
> tools = AsyncBrowserToolset(
> driver,
> members=BROWSER_MEMBERS,
> confirm=confirm,
> url_policy=allow_url,
> )
> ```
>
> The driver also supports `run_script` for approved page JavaScript.
> A script timeout stops waiting; it does not guarantee that page execution stops.
> **Existing sessions and local browsers**
>
> Pass a connected `BrowserSession` to `BrowserUse(browser=session)` to reuse your browser.
> Your application keeps responsibility for that session.
>
> Use `BrowserUse()` for a local browser.
> Install local Chromium with `uvx browser-use install` first.
> **Element references and supported features**
>
> Read the page before using an element reference.
> Page reads preserve references for existing elements.
> Navigation and detached elements can invalidate references.
>
> Page reads preserve the main document's accessibility tree, including hierarchy, control states, and field values.
> Page reads, page text, and JavaScript results stop at 10,000 characters and report truncation.
> Use scoped reads or `find` for specific content.
> `find` searches the complete tree before limiting its output.
> The driver retries page reads and screenshots once after a failure.
> It reconnects once when browser state fails.
> Persistent state failures still stop the OpenAI runner.
> It does not replay clicks or typing after uncertain effects.
> Page reads do not guarantee complete iframe or shadow-root coverage.
> Use screenshots and coordinate actions when necessary.
>
> Scoped reads discover page regions and return references for their controls.
> Diagnostics capture console messages and network responses after the driver first accesses a tab.
> Network reports exclude query strings, headers, and request bodies.
>
> File tools require application-issued grants.
> Your application calls `await driver.grant_upload(path, target=ref, tab_id=tab_id)` for an approved upload.
> Your application calls `await driver.grant_download(url, path, tab_id=tab_id)` for an approved download.
> Pass the returned grant ID to the model for its `upload_file` or `download_file` call.
>
> Each grant permits one transfer in the original document.
> Uploads capture the approved file bytes when your application creates the grant.
> Downloads create a new file on your application host.
> Both tools support files up to 10 MB (10,000,000 bytes).
> Enabling file tools does not create file grants automatically.
> Downloads use browser fetch and follow browser cross-origin rules.
> Downloads reject redirects.
> Uploads use the page's file input and dispatch input and change events.
> **Permissions and custom HTTP clients**
>
> The toolset checks inputs and calls your confirmation callback before actions.
> The URL callback checks requested navigation; it does not replace network controls.
>
> OpenAI 3.x uses `httpx2`.
> Use OpenAI's `DefaultAsyncHttpxClient` for custom HTTP clients.
See the [OpenAI browser helper reference](https://github.com/openai/openai-python/blob/v3.31.0/docs/browser.md).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.