+
+
+Browser Use Cloud lands **81%** — ahead of every other cloud browser, and far above a plain headless browser (2%).
+
+We get there by forking Chromium rather than patching detection signals with stealth plugins, so the signals never appear in the first place. [Here's why that approach holds up as anti-bot systems tighten](https://browser-use.com/posts/bot-detection).
+
## What's included
-Every cloud browser session runs in a hardened Chromium fork with stealth enabled by default — no configuration needed.
+Every cloud browser session runs in a hardened Chromium fork with stealth enabled by default — no configuration needed. [Create a browser session](https://docs.browser-use.com/cloud/browser/create) and it is already on.
- **Anti-detect browser fingerprinting** — Canvas, WebGL, fonts, navigator, and other browser fingerprints are randomized per session to appear as a real user. Passes CreepJS, BrowserLeaks, and other fingerprint detectors.
- **Ad and cookie banner blocking** — Banners are dismissed automatically so the agent sees clean pages and executes faster.
- **Cloudflare / anti-bot bypass** — Works on sites protected by Cloudflare, PerimeterX, and other bot detection services.
+Stealth keeps most challenges from ever appearing. When one does, it is solved automatically — see [CAPTCHA solving](https://docs.browser-use.com/cloud/browser/captcha) for per-vendor success rates.
+
## Residential proxies
Residential proxies are enabled by default across 195+ countries. This makes browser sessions appear as real users from the target geography. See [Proxies](https://docs.browser-use.com/cloud/browser/proxies) for details on geo-targeting and custom proxy configuration.
+## Further reading
+
+- [Benchmarks](https://browser-use.com/benchmarks) — 84.8% on BrowserBench and 81% bypass on high-security sites, against other providers
+- [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark)
+- [Browser agent bot detection is about to change](https://browser-use.com/posts/bot-detection)
+- [Stealth Browser Infrastructure](https://browser-use.com/posts/browser-infra)
+
+
+# CAPTCHA Solving
+Source: https://docs.browser-use.com/cloud/browser/captcha
+
+
+Browser Use remote browsers have **automatic CAPTCHA solving** built in. There is nothing to configure — on the browser, the attached agent, or your automation library (Playwright, Puppeteer, Selenium). It is on by default on every plan, including the [free tier](https://docs.browser-use.com/cloud/pricing).
+
+The best defense is not tripping a challenge in the first place — that is what [stealth](https://docs.browser-use.com/cloud/browser/stealth) handles (anti-fingerprinting and bot-detection bypass). This page covers what happens when a CAPTCHA or anti-bot system appears anyway: we solve it, and we lead the field on success rate.
+
+## Success rate by vendor
+
+Across the anti-bot and CAPTCHA systems agents hit most, Browser Use Cloud has the **highest overall success rate at 81%** — and the best against **Cloudflare (93%)** and **PerimeterX (81%)**.
+
+| Protection | Browser Use Cloud |
+| --- | --- |
+| Overall | **81%** |
+| Cloudflare | **93%** |
+| PerimeterX | **81%** |
+| Akamai | 85% |
+| DataDome | 69% |
+| reCAPTCHA | 80% |
+
+
+ 
+
+
+Full methodology in [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark).
+
+## Supported CAPTCHA types
+
+These are the interactive CAPTCHA widgets solved automatically, distinct from the anti-bot systems above (Cloudflare, DataDome, PerimeterX, Akamai) that gate a site before a widget ever appears:
+
+| CAPTCHA type | Solved automatically |
+| --- | --- |
+| reCAPTCHA v2 (checkbox / image challenge) | Yes |
+| reCAPTCHA v3 (score-based) | Yes |
+| hCaptcha | Yes |
+| Cloudflare Turnstile | Yes |
+
+All are handled on by default — no `captcha_type` parameter or per-widget configuration.
+
+## Get started
+
+There is nothing to turn on. CAPTCHA solving comes with every session. Start one:
+
+SDK, REST, or a single WebSocket URL.
+Playwright, Puppeteer, or Selenium over CDP.
+What the hardened Chromium fork does.
+Residential IPs in 195+ countries, on by default.
+
+## FAQ
+
+**Does the open-source library solve CAPTCHAs?**
+
+Without remote browsers, [open-source](https://github.com/browser-use/browser-use) agents have no stealth or CAPTCHA solving. Giving your agent stealth is easy: run it on a remote browser with a single parameter. See [Cloud browser + open source agent](https://docs.browser-use.com/cloud/browser/open-source-agent).
+
+**Can I use a third-party CAPTCHA solver?**
+
+No, we do not support third-party CAPTCHA solver plugins on the browser. If your CAPTCHAs are not being solved properly, reach out and we will look into it.
+
+**Do I need to enable anything for CAPTCHA solving?**
+
+No. Remote browsers solve CAPTCHAs for you automatically.
+
+## Further reading
+
+- [Prove you are a robot: CAPTCHAs for agents](https://browser-use.com/posts/prove-you-are-a-robot)
+- [Browser agent bot detection is about to change](https://browser-use.com/posts/bot-detection)
+
# Proxies
Source: https://docs.browser-use.com/cloud/browser/proxies
@@ -1080,12 +1682,12 @@ from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
browser = await client.browsers.create(
-custom_proxy={
- "host": "proxy.example.com",
- "port": 8080,
- "username": "user",
- "password": "pass",
-},
+ custom_proxy={
+ "host": "proxy.example.com",
+ "port": 8080,
+ "username": "user",
+ "password": "pass",
+ },
)
```
```typescript TypeScript
@@ -1094,14 +1696,119 @@ import { BrowserUse } from "browser-use-sdk/v3";
const client = new BrowserUse();
const browser = await client.browsers.create({
customProxy: {
-host: "proxy.example.com",
-port: 8080,
-username: "user",
-password: "pass",
+ host: "proxy.example.com",
+ port: 8080,
+ username: "user",
+ password: "pass",
},
});
```
+## Blocked? Get a fresh IP
+
+Browser Use does not rotate the IP within a running session. When a site starts blocking you, stop the session and create a new one — each session gets a fresh residential IP from the country pool automatically.
+
+```python Python
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+client = AsyncBrowserUse()
+
+async def with_fresh_ip(country="us", profile_id=None):
+ # Stop-and-recreate is how you get a new IP; reattach a profile to keep login state.
+ browser = await client.browsers.create(proxy_country_code=country, profile_id=profile_id)
+ return browser
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v3";
+
+const client = new BrowserUse();
+
+async function withFreshIp(country = "us", profileId?: string) {
+ // Stop-and-recreate is how you get a new IP; reattach a profile to keep login state.
+ return client.browsers.create({ proxyCountryCode: country, profileId });
+}
+```
+
+- **New session = new IP.** Recreating the browser is the supported way to rotate.
+- **Keep your login across the rotation** by passing the same [`profile_id`](https://docs.browser-use.com/cloud/guides/authentication) — the fresh IP loads the saved cookies and localStorage.
+- **Switch country** (`proxy_country_code`) to leave a blocked regional pool entirely.
+- **Custom proxies** can rotate per request on their side — use the `custom_proxy` config above with a rotating endpoint.
+
+## Further reading
+
+- [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark) — how proxy quality affects bypass rates
+
+
+# Screenshots
+Source: https://docs.browser-use.com/cloud/browser/screenshots
+
+
+A cloud browser session is a normal CDP endpoint, so screenshots work the way your framework takes them, and they save wherever your code runs.
+
+## Where screenshots are saved
+
+The most-asked question first: screenshots taken through Playwright or Puppeteer are written by *your* code, to a path *you* choose. Nothing is stored on the session unless you enable [recording](https://docs.browser-use.com/cloud/browser/sessions#recordings-and-downloads).
+
+```python Python
+from playwright.async_api import async_playwright
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+client = AsyncBrowserUse()
+browser = await client.browsers.create()
+
+async with async_playwright() as p:
+ pw = await p.chromium.connect_over_cdp(browser.cdp_url)
+ page = pw.contexts[0].pages[0]
+ await page.goto("https://example.com")
+ await page.screenshot(path="shots/example.png") # your machine, your path
+
+await client.browsers.stop(browser.id)
+```
+```typescript TypeScript
+import { chromium } from "playwright";
+import { BrowserUse } from "browser-use-sdk/v3";
+
+const client = new BrowserUse();
+const browser = await client.browsers.create();
+
+const pw = await chromium.connectOverCDP(browser.cdpUrl);
+const page = pw.contexts()[0].pages()[0];
+await page.goto("https://example.com");
+await page.screenshot({ path: "shots/example.png" });
+
+await client.browsers.stop(browser.id);
+```
+
+## Full page, not just the viewport
+
+By default a screenshot captures the visible viewport. For the whole page, top to bottom:
+
+```python
+await page.screenshot(path="full.png", full_page=True)
+```
+
+Playwright stitches the scroll automatically. The result contains page content only, no URL bar or browser chrome, because CDP screenshots capture the rendered page, not the window.
+
+## Resolution
+
+Screenshot dimensions follow the browser's screen size, set at [session creation](https://docs.browser-use.com/cloud/browser/create) with `browserScreenWidth` and `browserScreenHeight` (320–6144 × 320–3456). Set them explicitly if screenshots must match a target resolution:
+
+```python
+browser = await client.browsers.create(browser_screen_width=1920, browser_screen_height=1080)
+```
+
+{/* TEAM REVIEW: document the default screen size when width/height are omitted, and whether recording resolution (1920x1080 reported by users) can differ from screenshot resolution — a user reported 1512x770 screenshots vs 1920x1080 recordings. */}
+
+## Screenshots vs recording
+
+Screenshots are moments; [recording](https://docs.browser-use.com/cloud/browser/sessions#recordings-and-downloads) is the whole session as video (`enableRecording: true` at create, `recordingUrl` after stop). For debugging agent behavior, recording is usually what you want; for artifacts and QA evidence, screenshots.
+
+## From agent tasks
+
+Ask the agent to take screenshots as part of a task and collect them from the run's [workspace files](https://docs.browser-use.com/cloud/agent/workspaces).
+
+{/* TEAM REVIEW: add the exact API for retrieving agent step screenshots (the v1 /screenshots endpoint users reference) and note whether those images carry element highlight overlays — users ask for unmarked versions. */}
+
# Live preview & recording
Source: https://docs.browser-use.com/cloud/browser/live-preview
@@ -1194,14 +1901,14 @@ from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"Check how many GitHub stars browser-use has",
-enable_recording=True,
+ "Check how many GitHub stars browser-use has",
+ enable_recording=True,
)
# Waits up to 15s for recording to be ready. Returns [] if no browser was opened.
urls = await client.sessions.wait_for_recording(result.id)
for url in urls:
-print(url) # presigned MP4 download URL
+ print(url) # presigned MP4 download URL
```
```typescript TypeScript
import { BrowserUse } from "browser-use-sdk/v3";
@@ -1242,29 +1949,32 @@ console.log(stopped.recordingUrl); // presigned MP4 download URL
-# Playwright, Puppeteer, Selenium
-Source: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium
+# Playwright
+Source: https://docs.browser-use.com/cloud/browser/playwright
+
+Run your Playwright scripts on Browser Use's cloud browsers. Every session runs in a [hardened Chromium fork](https://docs.browser-use.com/cloud/browser/stealth) with stealth, anti-fingerprinting, and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) enabled by default — no configuration needed.
-Every session runs in a [hardened Chromium fork](https://docs.browser-use.com/cloud/browser/stealth) with stealth, anti-fingerprinting, and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) enabled by default — no configuration needed.
+When to use this:
+- You have existing Playwright scripts and want to run them on stealth infrastructure
+- You need pixel-perfect control (screenshots, specific click coordinates, form filling)
+- You want to combine agent tasks with manual browser automation
## Option 1: WebSocket URL (no SDK)
Connect with a single URL. All configuration is passed as query parameters.
-### Playwright
-
```python Python
from playwright.async_api import async_playwright
WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us"
async with async_playwright() as p:
-browser = await p.chromium.connect_over_cdp(WSS_URL)
-page = browser.contexts[0].pages[0]
-await page.goto("https://example.com")
-print(await page.title())
-await browser.close()
+ browser = await p.chromium.connect_over_cdp(WSS_URL)
+ page = browser.contexts[0].pages[0]
+ await page.goto("https://example.com")
+ print(await page.title())
+ await browser.close()
# Browser is automatically stopped when the WebSocket disconnects
```
```typescript TypeScript
@@ -1280,40 +1990,7 @@ await browser.close();
// Browser is automatically stopped when the WebSocket disconnects
```
-### Puppeteer
-
-```typescript
-import puppeteer from "puppeteer-core";
-
-const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";
-
-const browser = await puppeteer.connect({ browserWSEndpoint: WSS_URL });
-const [page] = await browser.pages();
-await page.goto("https://example.com");
-console.log(await page.title());
-await browser.close();
-```
-
-### Selenium
-
-Selenium requires a local WebSocket proxy to connect to Browser Use's remote CDP endpoint. Use [selenium-wire](https://github.com/wkeeling/selenium-wire) or connect through Playwright's CDP bridge instead:
-
-```python
-from playwright.sync_api import sync_playwright
-
-WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us"
-
-with sync_playwright() as p:
-browser = p.chromium.connect_over_cdp(WSS_URL)
-page = browser.contexts[0].pages[0]
-page.goto("https://example.com")
-print(page.title())
-browser.close()
-```
-
- Selenium's `debugger_address` only supports local `host:port` connections. For remote CDP over WebSocket, use Playwright or Puppeteer instead.
-
-## Query parameters
+### Query parameters
| Parameter | Type | Description |
|-----------|------|-------------|
@@ -1326,9 +2003,7 @@ browser.close()
## Option 2: SDK
-Create a browser via the SDK, get a `cdp_url`, and connect with Playwright or Puppeteer.
-
-### Playwright
+Create a browser via the SDK, get a `cdp_url`, and connect. The SDK also gives you a `live_url` to [watch or embed the session](https://docs.browser-use.com/cloud/browser/live-preview).
```python Python
from browser_use_sdk.v3 import AsyncBrowserUse
@@ -1340,11 +2015,11 @@ print(browser.cdp_url) # https://uuid.cdpN.browser-use.com
print(browser.live_url) # https://live.browser-use.com?wss=...
async with async_playwright() as p:
-pw_browser = await p.chromium.connect_over_cdp(browser.cdp_url)
-page = pw_browser.contexts[0].pages[0]
-await page.goto("https://example.com")
-print(await page.title())
-await pw_browser.close()
+ pw_browser = await p.chromium.connect_over_cdp(browser.cdp_url)
+ page = pw_browser.contexts[0].pages[0]
+ await page.goto("https://example.com")
+ print(await page.title())
+ await pw_browser.close()
await client.browsers.stop(browser.id)
```
@@ -1366,68 +2041,401 @@ await pwBrowser.close();
await client.browsers.stop(browser.id);
```
-### Puppeteer
+### Create response
-```typescript
-import { BrowserUse } from "browser-use-sdk/v3";
-import puppeteer from "puppeteer-core";
+`browsers.create()` wraps `POST https://api.browser-use.com/api/v3/browsers`, which returns `201` with:
-const client = new BrowserUse();
-const browser = await client.browsers.create();
+```json
+{
+ "id": "0d5f16f3-96cc-4d5f-a5a4-4a4d3b5f9d2e",
+ "status": "active",
+ "liveUrl": "https://live.browser-use.com?wss=...",
+ "cdpUrl": "https://0d5f16f3.cdp1.browser-use.com",
+ "timeoutAt": "2026-07-14T20:15:00Z",
+ "startedAt": "2026-07-14T20:00:00Z",
+ "finishedAt": null,
+ "proxyUsedMb": "0.0",
+ "proxyCost": "0.0",
+ "browserCost": "0.0",
+ "agentSessionId": null,
+ "recordingUrl": null
+}
+```
-// Puppeteer needs the WebSocket URL from /json/version
-const resp = await fetch(`${browser.cdpUrl}/json/version`);
-const { webSocketDebuggerUrl } = await resp.json();
+Field names are camelCase in the REST API and TypeScript SDK (`cdpUrl`, `liveUrl`) and snake_case in the Python SDK (`cdp_url`, `live_url`). `cdpUrl` and `liveUrl` are nullable — check them before connecting.
-const pwBrowser = await puppeteer.connect({ browserWSEndpoint: webSocketDebuggerUrl });
-const [page] = await pwBrowser.pages();
-await page.goto("https://example.com");
-console.log(await page.title());
-await pwBrowser.close();
+### Stopping a session over REST
-await client.browsers.stop(browser.id);
+There is no `POST /browsers/{id}/stop` endpoint. Stopping is an update:
+
+```bash
+curl -X PATCH "https://api.browser-use.com/api/v3/browsers/$SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action": "stop"}'
```
- Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+## Gotchas
+ Use `connect_over_cdp()` / `connectOverCDP()`, **not** `connect()`. Playwright's `connect()` expects a Playwright-protocol server and fails against a CDP endpoint with an opaque `Protocol error (Browser.getVersion)`.
-# Profiles
-Source: https://docs.browser-use.com/cloud/guides/authentication
+- **Reuse the existing context.** The session already has a context and page open — use `browser.contexts[0].pages[0]` instead of `browser.new_context()`, so you keep the stealth fingerprint and any loaded [profile](https://docs.browser-use.com/cloud/browser/playwright#query-parameters).
+- **Closing the connection vs stopping the session.** With the WebSocket URL, disconnecting stops the browser. With the SDK, `pw_browser.close()` only disconnects your client — call `client.browsers.stop(browser.id)` to end the session.
+ Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+
+## See also
+
+- [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer) and [Selenium](https://docs.browser-use.com/cloud/browser/selenium) connections
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — watch the session or embed it in your app
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies) and [stealth](https://docs.browser-use.com/cloud/browser/stealth) configuration
+
+
+# Puppeteer
+Source: https://docs.browser-use.com/cloud/browser/puppeteer
+
+
+Run your Puppeteer scripts on Browser Use's cloud browsers. Every session runs in a [hardened Chromium fork](https://docs.browser-use.com/cloud/browser/stealth) with stealth, anti-fingerprinting, and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) enabled by default — no configuration needed.
+
+When to use this:
+- You have existing Puppeteer scripts and want to run them on stealth infrastructure
+- You want low-level CDP control from Node.js without managing Chrome yourself
+- You want to combine agent tasks with manual browser automation
+
+## Option 1: WebSocket URL (no SDK)
+
+Connect with a single URL. All configuration is passed as query parameters.
+
+```typescript
+import puppeteer from "puppeteer-core";
+
+const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";
+
+const browser = await puppeteer.connect({ browserWSEndpoint: WSS_URL });
+const [page] = await browser.pages();
+await page.goto("https://example.com");
+console.log(await page.title());
+await browser.close();
+// Browser is automatically stopped when the WebSocket disconnects
+```
+
+### Query parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiKey` | `string` | **Required.** Your Browser Use API key. |
+| `proxyCountryCode` | `string` | Proxy country code (e.g. `us`, `de`, `jp`). 195+ countries. |
+| `profileId` | `string` | Load a saved browser profile (cookies, localStorage). |
+| `timeout` | `int` | Session timeout in minutes. Default: 15. Max: 240 (4 hours). |
+| `browserScreenWidth` | `int` | Browser width in pixels. |
+| `browserScreenHeight` | `int` | Browser height in pixels. |
+
+## Option 2: SDK
+
+Create a browser via the SDK, then resolve the WebSocket endpoint. Unlike Playwright, Puppeteer can't connect to an HTTP CDP URL directly — fetch `/json/version` to get the `webSocketDebuggerUrl` first.
+
+```typescript
+import { BrowserUse } from "browser-use-sdk/v3";
+import puppeteer from "puppeteer-core";
+
+const client = new BrowserUse();
+const browser = await client.browsers.create();
+
+// Puppeteer needs the WebSocket URL from /json/version
+const resp = await fetch(`${browser.cdpUrl}/json/version`);
+const { webSocketDebuggerUrl } = await resp.json();
+
+const pptrBrowser = await puppeteer.connect({ browserWSEndpoint: webSocketDebuggerUrl });
+const [page] = await pptrBrowser.pages();
+await page.goto("https://example.com");
+console.log(await page.title());
+await pptrBrowser.close();
+
+await client.browsers.stop(browser.id);
+```
+
+The SDK also gives you a `liveUrl` to [watch or embed the session](https://docs.browser-use.com/cloud/browser/live-preview).
+
+### Create response
+
+`browsers.create()` wraps `POST https://api.browser-use.com/api/v3/browsers`, which returns `201` with:
+
+```json
+{
+ "id": "0d5f16f3-96cc-4d5f-a5a4-4a4d3b5f9d2e",
+ "status": "active",
+ "liveUrl": "https://live.browser-use.com?wss=...",
+ "cdpUrl": "https://0d5f16f3.cdp1.browser-use.com",
+ "timeoutAt": "2026-07-14T20:15:00Z",
+ "startedAt": "2026-07-14T20:00:00Z",
+ "finishedAt": null,
+ "proxyUsedMb": "0.0",
+ "proxyCost": "0.0",
+ "browserCost": "0.0",
+ "agentSessionId": null,
+ "recordingUrl": null
+}
+```
+
+Field names are camelCase in the REST API and TypeScript SDK (`cdpUrl`, `liveUrl`). `cdpUrl` and `liveUrl` are nullable — check them before connecting.
+
+### Stopping a session over REST
+
+There is no `POST /browsers/{id}/stop` endpoint. Stopping is an update:
+
+```bash
+curl -X PATCH "https://api.browser-use.com/api/v3/browsers/$SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action": "stop"}'
+```
+
+## Gotchas
+
+- **Use `puppeteer-core`.** It's the connect-only package — installing full `puppeteer` downloads a local Chromium you'll never use.
+- **`browserWSEndpoint` must be a `ws://`/`wss://` URL.** Passing the SDK's HTTPS `cdpUrl` directly fails; resolve it via `/json/version` as shown above.
+- **Viewport.** Puppeteer applies its own 800×600 default viewport after connecting. Pass `defaultViewport: null` to `puppeteer.connect()` to keep the browser's real window size.
+- **Closing the connection vs stopping the session.** With the WebSocket URL, disconnecting stops the browser. With the SDK, `browser.close()` only disconnects your client — call `client.browsers.stop(browser.id)` to end the session.
+
+ Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+
+## See also
+
+- [Playwright](https://docs.browser-use.com/cloud/browser/playwright) and [Selenium](https://docs.browser-use.com/cloud/browser/selenium) connections
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — watch the session or embed it in your app
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies) and [stealth](https://docs.browser-use.com/cloud/browser/stealth) configuration
+
+
+# Selenium
+Source: https://docs.browser-use.com/cloud/browser/selenium
+
+
+Browser Use's cloud browsers speak Chrome DevTools Protocol (CDP) over a remote WebSocket. Selenium can't consume that natively: its `debugger_address` option only supports local `host:port` connections, not remote `wss://` URLs.
+
+You have two practical paths.
+
+## Recommended: bridge through a CDP client
+
+If you're migrating Selenium scripts, connect through Playwright's sync API — the page-automation model (navigate, locate, click, read) maps one-to-one, and you get the [hardened stealth Chromium](https://docs.browser-use.com/cloud/browser/stealth) and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) with no configuration.
+
+```python
+from playwright.sync_api import sync_playwright
+
+WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us"
+
+with sync_playwright() as p:
+ browser = p.chromium.connect_over_cdp(WSS_URL)
+ page = browser.contexts[0].pages[0]
+ page.goto("https://example.com")
+ print(page.title())
+ browser.close()
+# Browser is automatically stopped when the WebSocket disconnects
+```
+
+Common Selenium → Playwright equivalents:
+
+| Selenium | Playwright (sync) |
+|---|---|
+| `driver.get(url)` | `page.goto(url)` |
+| `driver.find_element(By.CSS_SELECTOR, s)` | `page.locator(s)` |
+| `element.click()` | `page.locator(s).click()` |
+| `element.send_keys(text)` | `page.locator(s).fill(text)` |
+| `driver.title` | `page.title()` |
+| `WebDriverWait(...).until(...)` | built-in auto-waiting |
+| `driver.quit()` | `browser.close()` |
+
+### Query parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiKey` | `string` | **Required.** Your Browser Use API key. |
+| `proxyCountryCode` | `string` | Proxy country code (e.g. `us`, `de`, `jp`). 195+ countries. |
+| `profileId` | `string` | Load a saved browser profile (cookies, localStorage). |
+| `timeout` | `int` | Session timeout in minutes. Default: 15. Max: 240 (4 hours). |
+| `browserScreenWidth` | `int` | Browser width in pixels. |
+| `browserScreenHeight` | `int` | Browser height in pixels. |
+
+## Alternative: keep Selenium with a local proxy
+
+If you must keep the Selenium API, run a local WebSocket-to-TCP proxy so Chrome's remote debugging endpoint appears as a local `host:port`, e.g. via [selenium-wire](https://github.com/wkeeling/selenium-wire). This adds a moving part we don't manage — for new code, prefer the CDP bridge above.
+
+ Selenium's `debugger_address` only supports local `host:port` connections. For remote CDP over WebSocket, use [Playwright](https://docs.browser-use.com/cloud/browser/playwright) or [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer) instead.
+
+ Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+
+## See also
+
+- [Playwright](https://docs.browser-use.com/cloud/browser/playwright) and [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer) connections
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — watch the session or embed it in your app
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies) and [stealth](https://docs.browser-use.com/cloud/browser/stealth) configuration
+
+
+# Cloud browser + open source agent
+Source: https://docs.browser-use.com/cloud/browser/open-source-agent
+
+
+The [open-source library](/open-source/introduction) runs the agent on your machine. By default it also runs the *browser* on your machine, which means no stealth, no residential proxy, and no CAPTCHA solving. This page connects the two: keep your local agent code, point it at a cloud browser.
+
+## Connect by CDP URL
+
+Create a cloud browser, then pass its CDP URL to the library's `Browser`:
+
+```python
+import asyncio
+from browser_use import Agent, Browser, ChatOpenAI
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+async def main():
+ client = AsyncBrowserUse()
+ cloud_browser = await client.browsers.create(proxy_country_code="us")
+
+ try:
+ agent = Agent(
+ task="Find the current price of iPhone 16 on amazon.de",
+ llm=ChatOpenAI(model="gpt-4o"),
+ browser=Browser(cdp_url=cloud_browser.cdp_url),
+ )
+ await agent.run()
+ finally:
+ await client.browsers.stop(cloud_browser.id)
+
+asyncio.run(main())
+```
+
+The agent behaves exactly as it does locally. The browser it drives is a [stealth Chromium](https://docs.browser-use.com/cloud/browser/stealth) with [CAPTCHA solving](https://docs.browser-use.com/cloud/browser/captcha) and a [residential proxy](https://docs.browser-use.com/cloud/browser/proxies), and you can watch it work through the session's `live_url`.
+
+{/* TEAM REVIEW: confirm the `use_cloud=True` shorthand on Browser() — parameter name, minimum library version, and whether it should be the primary example instead of the cdp_url form. */}
+
+## What you get, what you keep
+
+| | Stays yours | Comes from Cloud |
+|---|---|---|
+| Agent loop, prompts, custom tools | ✓ | |
+| LLM choice and API keys | ✓ | |
+| Browser runtime | | ✓ stealth Chromium |
+| Proxy / IP | | ✓ residential, 195+ countries |
+| CAPTCHA handling | | ✓ automatic |
+| Live view and recording | | ✓ per session |
+
+Billing: only the browser session ($0.02/hour plus proxy data). Your LLM tokens go to your own provider.
+
+## Related
+
+- [Create a browser session](https://docs.browser-use.com/cloud/browser/create) — all session parameters
+- [Open source vs Cloud](https://docs.browser-use.com/cloud/open-source-vs-cloud) — the full decision guide
+- [Manage browser sessions](https://docs.browser-use.com/cloud/browser/sessions) — always stop sessions when done
+
+
+# Profiles
+Source: https://docs.browser-use.com/cloud/guides/authentication
+
+
+Create a profile, then pass its `profile_id` to `run()` — the agent opens a browser seeded from that profile and runs your task on it. Cookies and login state saved during the run persist, so the next run with the same profile is already logged in.
```python Python
from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
+
+# 1. Create a profile (stores cookies + login state across runs)
profile = await client.profiles.create(name="user-id-1")
-# or search existing
+# or reuse an existing one:
# profile = (await client.profiles.list(query="user-id-1")).items[0]
-session = await client.sessions.create(profile_id=profile.id)
-result = await client.run("Check browser-use github stars", session_id=session.id)
-print(result.output)
-# Always stop the session to persist profile state
-await client.sessions.stop(session.id)
+# 2. Run the agent — profile_id attaches a browser seeded from the profile
+result = await client.run(
+ "Go to example.com and return the page title",
+ profile_id=profile.id,
+)
+print(result.output) # -> "Example Domain"
+
+# 3. Reuse the same profile later — saved login/cookies carry over
+followup = await client.run("Check my GitHub notifications", profile_id=profile.id)
```
```typescript TypeScript
import { BrowserUse } from "browser-use-sdk/v3";
const client = new BrowserUse();
+
+// 1. Create a profile (stores cookies + login state across runs)
const profile = await client.profiles.create({ name: "user-id-1" });
-// or search existing
+// or reuse an existing one:
// const profile = (await client.profiles.list({ query: "user-id-1" })).items[0];
-const session = await client.sessions.create({ profileId: profile.id });
-const result = await client.run("Check browser-use github stars", {
- sessionId: session.id,
+
+// 2. Run the agent — profileId attaches a browser seeded from the profile
+const result = await client.run("Go to example.com and return the page title", {
+ profileId: profile.id,
});
-console.log(result.output);
+console.log(result.output); // -> "Example Domain"
-// Always stop the session to persist profile state
-await client.sessions.stop(session.id);
+// 3. Reuse the same profile later — saved login/cookies carry over
+const followup = await client.run("Check my GitHub notifications", { profileId: profile.id });
```
+Passing `profile_id` to `run()` provisions the browser and runs the agent in one call — no separate session step. Profile state is saved automatically when the run ends.
+
View your profile IDs at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=profiles).
+## Persist state on a browser you drive (CDP)
+
+Profiles work the same whether the agent drives or you do. Pass `profile_id` to `browsers.create()`, set state over CDP, then **stop the browser to flush cookies and localStorage into the profile**. Reconnect later with the same `profile_id` and the state is there.
+
+```python Python
+from browser_use_sdk.v3 import AsyncBrowserUse
+from playwright.async_api import async_playwright
+
+client = AsyncBrowserUse()
+profile = await client.profiles.create(name="persist-demo")
+
+# Session 1 — write state, then stop to persist
+b1 = await client.browsers.create(profile_id=profile.id)
+async with async_playwright() as p:
+ pw = await p.chromium.connect_over_cdp(b1.cdp_url)
+ page = pw.contexts[0].pages[0]
+ await page.goto("https://en.wikipedia.org")
+ await page.evaluate("localStorage.setItem('demo', 'hello')")
+ await pw.close()
+await client.browsers.stop(b1.id) # flushes state into the profile
+
+# Session 2 — same profile, state is back
+b2 = await client.browsers.create(profile_id=profile.id)
+async with async_playwright() as p:
+ pw = await p.chromium.connect_over_cdp(b2.cdp_url)
+ page = pw.contexts[0].pages[0]
+ await page.goto("https://en.wikipedia.org")
+ value = await page.evaluate("localStorage.getItem('demo')")
+ print(value) # -> hello
+ await pw.close()
+await client.browsers.stop(b2.id)
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v3";
+import { chromium } from "playwright";
+
+const client = new BrowserUse();
+const profile = await client.profiles.create({ name: "persist-demo" });
+
+// Session 1 — write state, then stop to persist
+const b1 = await client.browsers.create({ profileId: profile.id });
+let pw = await chromium.connectOverCDP(b1.cdpUrl);
+let page = pw.contexts()[0].pages()[0];
+await page.goto("https://en.wikipedia.org");
+await page.evaluate(() => localStorage.setItem("demo", "hello"));
+await pw.close();
+await client.browsers.stop(b1.id); // flushes state into the profile
+
+// Session 2 — same profile, state is back
+const b2 = await client.browsers.create({ profileId: profile.id });
+pw = await chromium.connectOverCDP(b2.cdpUrl);
+page = pw.contexts()[0].pages()[0];
+await page.goto("https://en.wikipedia.org");
+console.log(await page.evaluate(() => localStorage.getItem("demo"))); // -> hello
+await pw.close();
+await client.browsers.stop(b2.id);
+```
+
+ Use a site that actually sets cookies/localStorage to verify persistence — `example.com` sets none, so it is a poor test target.
+
## Manage profiles
```python Python
@@ -1437,7 +2445,7 @@ profile = await client.profiles.create(name="work-account")
# List all
response = await client.profiles.list()
for p in response.items:
-print(p.id, p.name)
+ print(p.id, p.name)
# Search by name
response = await client.profiles.list(query="user-id-1")
@@ -1480,10 +2488,14 @@ await client.profiles.delete(profileId);
- **Per-user profiles:** Create one profile per end-user. Query by name to get the profile ID, or store a mapping between your users and their profile IDs in your database.
- Profile state is only saved when the session ends. Always call `sessions.stop()` when you are done — if a session is left open or times out, changes may not be persisted. Every code path that uses a profile must stop the session, including error handlers.
+ Profile state is saved when the run ends — call `sessions.stop()` (agent) or `browsers.stop()` (CDP) when you are done. Both paths persist; a session left open or timed out may not save. Stop in a `finally` so every code path, including error handlers, persists.
+## Further reading
-# Sync local and cloud cookies
+- [How to authenticate AI web agents](https://browser-use.com/posts/web-agent-authentication)
+
+
+# Profiles / Cookie sync
Source: https://docs.browser-use.com/cloud/guides/profile-sync
@@ -1603,8 +2615,8 @@ print(f"Live view: {session.live_url}")
# Agent navigates to login
result = await client.run(
-"Go to example.com/login and enter username user@example.com and password mypassword, then stop before 2FA",
-session_id=session.id,
+ "Go to example.com/login and enter username user@example.com and password mypassword, then stop before 2FA",
+ session_id=session.id,
)
# Human completes 2FA in the live view
@@ -1612,8 +2624,8 @@ input("Complete 2FA in the live view, then press Enter...")
# Agent continues
result = await client.run(
-"You are now logged in. Go to the dashboard and export the monthly report",
-session_id=session.id,
+ "You are now logged in. Go to the dashboard and export the monthly report",
+ session_id=session.id,
)
print(result.output)
await client.sessions.stop(session.id)
@@ -1662,14 +2674,14 @@ from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"""
-1. Go to example.com/signup
-2. Sign up with the agent's email address (use the email available to you)
-3. Check your email inbox for the verification code
-4. Enter the code on the website
-5. Complete the registration
-""",
-agentmail=True, # default, shown for clarity
+ """
+ 1. Go to example.com/signup
+ 2. Sign up with the agent's email address (use the email available to you)
+ 3. Check your email inbox for the verification code
+ 4. Enter the code on the website
+ 5. Complete the registration
+ """,
+ agentmail=True, # default, shown for clarity
)
print(result.output)
```
@@ -1719,16 +2731,16 @@ client = AsyncBrowserUse()
totp_secret = "JBSWY3DPEHPK3PXP"
result = await client.run(
-f"""
-Log into example.com with username user@example.com and password mypassword.
-When prompted for a 2FA code, generate one using pyotp:
+ f"""
+ Log into example.com with username user@example.com and password mypassword.
+ When prompted for a 2FA code, generate one using pyotp:
-import pyotp
-totp = pyotp.TOTP("{totp_secret}")
-code = totp.now()
+ import pyotp
+ totp = pyotp.TOTP("{totp_secret}")
+ code = totp.now()
-Enter the generated code.
-""",
+ Enter the generated code.
+ """,
)
print(result.output)
```
@@ -1772,100 +2784,502 @@ Use **Agent Mail** (enabled by default). For end-client scenarios, have them for
Use **TOTP secret in prompt** — the agent generates codes via pyotp, no human intervention needed.
-# OpenClaw
-Source: https://docs.browser-use.com/cloud/tutorials/integrations/openclaw
+# Webhooks
+Source: https://docs.browser-use.com/cloud/guides/webhooks
-[OpenClaw](https://openclaw.ai) is a self-hosted gateway that connects chat apps like WhatsApp, Telegram, and Discord to AI coding agents. Add Browser Use and those agents get full browser automation — anti-detect profiles, CAPTCHA solving, residential proxies in 195+ countries, and stealth browsing out of the box.
+Set up webhooks at [cloud.browser-use.com/settings?tab=webhooks](https://cloud.browser-use.com/settings?tab=webhooks).
-Two ways to set it up: connect a Browser Use cloud browser to OpenClaw's native browser tool via CDP, or install the Browser Use CLI as a skill.
+## Events
-## Option 1: Cloud Browser via CDP
+| Event | When |
+|-------|------|
+| `agent.task.status_update` | Task status changes (`running`, `idle`, or `stopped`) |
+| `test` | Webhook test ping |
-OpenClaw has a built-in browser tool with its own CLI commands (`openclaw browser`). By default, it controls a local Chromium instance. You can point it at a Browser Use cloud browser instead by configuring a remote CDP profile.
+## Payload
-Browser Use exposes a WebSocket CDP URL. OpenClaw connects to it like any remote browser — no SDK or extra dependencies needed.
+```json
+{
+ "type": "agent.task.status_update",
+ "timestamp": "2025-01-15T10:30:00Z",
+ "payload": {
+ "task_id": "task_abc123",
+ "session_id": "session_xyz",
+ "status": "idle",
+ "metadata": {}
+ }
+}
+```
-### Setup
+## Signature verification
-**1. Get your API key**
+Every webhook request includes two headers:
-Sign up at [cloud.browser-use.com](https://cloud.browser-use.com) and copy your API key from [Settings → API Keys](https://cloud.browser-use.com/settings?tab=api-keys&new=1).
+- `X-Browser-Use-Signature` — HMAC-SHA256 signature of the payload
+- `X-Browser-Use-Timestamp` — Unix timestamp (seconds) when the request was sent
-**2. Add a Browser Use profile**
+The signature is computed over `{timestamp}.{body}`, where `body` is the JSON-serialized payload with keys sorted alphabetically and no extra whitespace. Verify it to ensure the request is authentic and to prevent replay attacks.
-Open `~/.openclaw/openclaw.json` and add a `browser-use` profile:
+```python Python
+import hashlib
+import hmac
+import json
+import time
-```json5
-{
- browser: {
-enabled: true,
-defaultProfile: "browser-use",
-remoteCdpTimeoutMs: 3000,
-remoteCdpHandshakeTimeoutMs: 5000,
-profiles: {
- "browser-use": {
- cdpUrl: "wss://connect.browser-use.com?apiKey=
- {/* Chat column */}
-
+
-
-
- {/* Live browser view — liveUrl available from session creation */}
-
+ {/* Chat column */}
+
);
}
```
@@ -2362,6 +4007,116 @@ useSession();
| `client.sessions.waitForRecording()` | Get MP4 recording URLs |
+# Agent Sign Up for Browser Use
+Source: https://docs.browser-use.com/cloud/agent-signup
+
+
+An AI agent can create its own free Browser Use account without a human opening the dashboard. This is useful when an agent has terminal or HTTP access and needs a Browser Use API key before it can run cloud browser tasks.
+
+The flow is a Browser Use agent challenge: the agent requests a challenge, solves the math problem, verifies the answer, and receives an API key.
+
+## REST flow
+
+### 1. Request a challenge
+
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup \
+ -H "Content-Type: application/json" \
+ -d '{}'
+```
+
+Request body, optional (include a user email/name if available):
+
+```json
+{
+ "email": "user@example.com",
+ "name": "User Name"
+}
+```
+
+Response:
+
+```json
+{
+ "challenge_id": "uuid",
+ "challenge_text": "..."
+}
+```
+
+### 2. Solve the challenge
+
+Read `challenge_text` and solve the math problem. Return the answer as a string with two decimal places, for example `"144.00"`.
+
+### 3. Verify the answer
+
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup/verify \
+ -H "Content-Type: application/json" \
+ -d '{"challenge_id":"uuid","answer":"144.00"}'
+```
+
+Request body:
+
+```json
+{
+ "challenge_id": "uuid",
+ "answer": "144.00"
+}
+```
+
+Response:
+
+```json
+{
+ "api_key": "bu_..."
+}
+```
+
+Use the returned key for Browser Use Cloud API requests.
+
+For example, create a browser session:
+
+```bash
+curl -X POST https://api.browser-use.com/api/v3/browsers \
+ -H "X-Browser-Use-API-Key: bu_..." \
+ -H "Content-Type: application/json" \
+ -d '{}'
+```
+
+See the [Create Browser Session API reference](https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session).
+
+## Claim the account
+
+If a human wants to see the agent-created account in the dashboard later, the agent can create a claim link:
+
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup/claim \
+ -H "X-Browser-Use-API-Key: bu_..."
+```
+
+Response:
+
+```json
+{
+ "claim_url": "https://..."
+}
+```
+
+The claim URL is valid for 1 hour.
+
+## CLI usage
+
+Agents with shell access can use the Browser Use CLI after the REST flow returns an API key:
+
+```bash
+uv tool install browser-use
+export BROWSER_USE_API_KEY=bu_...
+browser-use auth status
+```
+
+Replace `bu_...` with the key returned by the REST flow.
+
+
# Grow Therapy provider search
Source: https://docs.browser-use.com/cloud/tutorials/grow-therapy-compare
@@ -2398,28 +4153,28 @@ const client = new BrowserUse();
```python Python
class Provider(BaseModel):
-name: str
-title: str
-specialties: list[str]
-insurance_plans: list[str]
-rating: float | None = None
-next_available: str | None = None
+ name: str
+ title: str
+ specialties: list[str]
+ insurance_plans: list[str]
+ rating: float | None = None
+ next_available: str | None = None
class ProviderSearch(BaseModel):
-providers: list[Provider]
-total_found: int | None = None
-location: str
-specialty: str
+ providers: list[Provider]
+ total_found: int | None = None
+ location: str
+ specialty: str
```
```typescript TypeScript
const ProviderSearch = z.object({
providers: z.array(z.object({
-name: z.string(),
-title: z.string(),
-specialties: z.array(z.string()),
-insurancePlans: z.array(z.string()),
-rating: z.number().nullable(),
-nextAvailable: z.string().nullable(),
+ name: z.string(),
+ title: z.string(),
+ specialties: z.array(z.string()),
+ insurancePlans: z.array(z.string()),
+ rating: z.number().nullable(),
+ nextAvailable: z.string().nullable(),
})),
totalFound: z.number().nullable(),
location: z.string(),
@@ -2440,19 +4195,19 @@ const workspace = await client.workspaces.create({ name: "grow-therapy-search" }
```python Python
result = await client.run(
-"Go to growtherapy.com and search for therapists in {{New York}} "
-"who specialize in {{anxiety}} and accept insurance. "
-"Return the first 5 provider profiles as JSON.",
-workspace_id=str(workspace.id),
-output_schema=ProviderSearch,
+ "Go to growtherapy.com and search for therapists in {{New York}} "
+ "who specialize in {{anxiety}} and accept insurance. "
+ "Return the first 5 provider profiles as JSON.",
+ workspace_id=str(workspace.id),
+ output_schema=ProviderSearch,
)
for p in result.output.providers:
-print(f"{p.name} ({p.title})")
-print(f" Specialties: {', '.join(p.specialties)}")
-print(f" Rating: {p.rating}")
-print(f" Next available: {p.next_available}")
-print()
+ print(f"{p.name} ({p.title})")
+ print(f" Specialties: {', '.join(p.specialties)}")
+ print(f" Rating: {p.rating}")
+ print(f" Next available: {p.next_available}")
+ print()
```
```typescript TypeScript
const result = await client.run(
@@ -2479,16 +4234,16 @@ locations = ["Los Angeles", "Chicago", "Houston", "Miami"]
specialties = ["depression", "trauma", "ADHD"]
for location in locations:
-for specialty in specialties:
- result = await client.run(
- f"Go to growtherapy.com and search for therapists in {{{{{location}}}}} "
- f"who specialize in {{{{{specialty}}}}} and accept insurance. "
- f"Return the first 5 provider profiles as JSON.",
- workspace_id=str(workspace.id),
- output_schema=ProviderSearch,
- )
- count = len(result.output.providers)
- print(f"{location} / {specialty}: {count} providers found")
+ for specialty in specialties:
+ result = await client.run(
+ f"Go to growtherapy.com and search for therapists in {{{{{location}}}}} "
+ f"who specialize in {{{{{specialty}}}}} and accept insurance. "
+ f"Return the first 5 provider profiles as JSON.",
+ workspace_id=str(workspace.id),
+ output_schema=ProviderSearch,
+ )
+ count = len(result.output.providers)
+ print(f"{location} / {specialty}: {count} providers found")
```
```typescript TypeScript
const locations = ["Los Angeles", "Chicago", "Houston", "Miami"];
@@ -2496,13 +4251,13 @@ const specialties = ["depression", "trauma", "ADHD"];
for (const location of locations) {
for (const specialty of specialties) {
-const result = await client.run(
- `Go to growtherapy.com and search for therapists in {{${location}}} ` +
- `who specialize in {{${specialty}}} and accept insurance. ` +
- `Return the first 5 provider profiles as JSON.`,
- { workspaceId: workspace.id, schema: ProviderSearch },
-);
-console.log(`${location} / ${specialty}: ${result.output.providers.length} providers`);
+ const result = await client.run(
+ `Go to growtherapy.com and search for therapists in {{${location}}} ` +
+ `who specialize in {{${specialty}}} and accept insurance. ` +
+ `Return the first 5 provider profiles as JSON.`,
+ { workspaceId: workspace.id, schema: ProviderSearch },
+ );
+ console.log(`${location} / ${specialty}: ${result.output.providers.length} providers`);
}
}
```
@@ -2587,7 +4342,6 @@ Source: https://docs.browser-use.com/cloud/legacy/agent
| Model | API String | Cost per Step |
| ----- | ---------- | ------------- |
| Browser Use 2.0 (default) | `browser-use-2.0` | \$0.006 |
-| Browser Use LLM | `browser-use-llm` | \$0.002 |
| O3 | `o3` | \$0.03 |
| Gemini Flash Latest | `gemini-flash-latest` | \$0.0075 |
| Gemini Flash Lite Latest | `gemini-flash-lite-latest` | \$0.005 |
@@ -2621,15 +4375,15 @@ client = AsyncBrowserUse()
session = await client.sessions.create()
upload = await client.files.session_url(
-session.id,
-file_name="input.pdf",
-content_type="application/pdf",
-size_bytes=1024,
+ session.id,
+ file_name="input.pdf",
+ content_type="application/pdf",
+ size_bytes=1024,
)
with open("input.pdf", "rb") as f:
-async with httpx.AsyncClient() as http:
- await http.post(upload.url, content=f.read(), headers={"Content-Type": "application/pdf"})
+ async with httpx.AsyncClient() as http:
+ await http.post(upload.url, content=f.read(), headers={"Content-Type": "application/pdf"})
result = await client.run("Summarize the uploaded PDF", session_id=session.id)
```
@@ -2662,8 +4416,8 @@ const result = await client.run("Summarize the uploaded PDF", { sessionId: sessi
```python Python
result = await client.tasks.get(task_id)
for file in result.output_files:
-output = await client.files.task_output(task_id, file.id)
-print(output.download_url) # download URL
+ output = await client.files.task_output(task_id, file.id)
+ print(output.download_url) # download URL
```
```typescript TypeScript
const result = await client.tasks.get(taskId);
@@ -2685,8 +4439,8 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
run = client.run("Find the most upvoted post on Reddit r/technology today")
async for step in run:
-print(f"Step {step.number}: {step.next_goal}")
-print(f" URL: {step.url}")
+ print(f"Step {step.number}: {step.next_goal}")
+ print(f" URL: {step.url}")
print(run.result.output) # final result after iteration
```
@@ -2767,8 +4521,8 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
skill = await client.skills.create(
-goal="Extract the top X posts from HackerNews. For each post return: title, URL, score, author, comment count, and rank. X is an input parameter.",
-agent_prompt="Go to https://news.ycombinator.com, click on the first post to load its content, go back to the list, and scroll down to trigger loading of additional posts.",
+ goal="Extract the top X posts from HackerNews. For each post return: title, URL, score, author, comment count, and rank. X is an input parameter.",
+ agent_prompt="Go to https://news.ycombinator.com, click on the first post to load its content, go back to the list, and scroll down to trigger loading of additional posts.",
)
print(skill.id)
```
@@ -2789,8 +4543,8 @@ Skill creation takes ~30 seconds. You can also create skills visually from the [
```python Python
result = await client.skills.execute(
-skill.id,
-parameters={"X": 10},
+ skill.id,
+ parameters={"X": 10},
)
print(result)
```
@@ -2862,9 +4616,9 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"Log into my Jira account and create a new ticket",
-op_vault_id="your-vault-id",
-allowed_domains=["*.atlassian.net"],
+ "Log into my Jira account and create a new ticket",
+ op_vault_id="your-vault-id",
+ allowed_domains=["*.atlassian.net"],
)
print(result.output)
```
@@ -2875,8 +4629,8 @@ const client = new BrowserUse();
const result = await client.run(
"Log into my Jira account and create a new ticket",
{
-opVaultId: "your-vault-id",
-allowedDomains: ["*.atlassian.net"],
+ opVaultId: "your-vault-id",
+ allowedDomains: ["*.atlassian.net"],
},
);
console.log(result.output);
@@ -2886,17 +4640,17 @@ For SSO/OAuth redirects, include all required domains:
```python Python
result = await client.run(
-"Log into Jira and create a ticket for the Q4 release",
-op_vault_id="your-vault-id",
-allowed_domains=["*.atlassian.net", "*.okta.com"],
+ "Log into Jira and create a ticket for the Q4 release",
+ op_vault_id="your-vault-id",
+ allowed_domains=["*.atlassian.net", "*.okta.com"],
)
```
```typescript TypeScript
const result = await client.run(
"Log into Jira and create a ticket for the Q4 release",
{
-opVaultId: "your-vault-id",
-allowedDomains: ["*.atlassian.net", "*.okta.com"],
+ opVaultId: "your-vault-id",
+ allowedDomains: ["*.atlassian.net", "*.okta.com"],
},
);
```
@@ -2924,9 +4678,9 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"Log into GitHub and star the browser-use/browser-use repo",
-secrets={"github.com": "username:password123"},
-allowed_domains=["github.com"],
+ "Log into GitHub and star the browser-use/browser-use repo",
+ secrets={"github.com": "username:password123"},
+ allowed_domains=["github.com"],
)
```
```typescript TypeScript
@@ -2936,8 +4690,8 @@ const client = new BrowserUse();
const result = await client.run(
"Log into GitHub and star the browser-use/browser-use repo",
{
-secrets: { "github.com": "username:password123" },
-allowedDomains: ["github.com"],
+ secrets: { "github.com": "username:password123" },
+ allowedDomains: ["github.com"],
},
);
```
@@ -2948,28 +4702,85 @@ For SSO/OAuth redirects, include all domains in the auth flow:
```python Python
result = await client.run(
-"Log into the company portal and download the Q4 report",
-secrets={
- "portal.example.com": "user@company.com:password123",
- "okta.com": "user@company.com:password123",
-},
-allowed_domains=["portal.example.com", "*.okta.com"],
+ "Log into the company portal and download the Q4 report",
+ secrets={
+ "portal.example.com": "user@company.com:password123",
+ "okta.com": "user@company.com:password123",
+ },
+ allowed_domains=["portal.example.com", "*.okta.com"],
)
```
```typescript TypeScript
const result = await client.run(
"Log into the company portal and download the Q4 report",
{
-secrets: {
- "portal.example.com": "user@company.com:password123",
- "okta.com": "user@company.com:password123",
-},
-allowedDomains: ["portal.example.com", "*.okta.com"],
+ secrets: {
+ "portal.example.com": "user@company.com:password123",
+ "okta.com": "user@company.com:password123",
+ },
+ allowedDomains: ["portal.example.com", "*.okta.com"],
},
);
```
+# API Reference
+Source: https://docs.browser-use.com/cloud/api-v4-overview
+
+
+## Authentication
+
+All requests require an API key in the `X-Browser-Use-API-Key` header:
+
+```
+X-Browser-Use-API-Key: bu_your_key_here
+```
+
+Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=api-keys&new=1). Keys start with `bu_`.
+
+## Base URL
+
+```
+https://api.browser-use.com/api/v4
+```
+
+## The core loop
+
+Create a run, poll its status until terminal, then fetch the full result. `status` is a cheap indexed lookup — poll it, not the full run.
+
+```bash Create a run
+curl -X POST https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: bu_your_key_here" \
+ -H "Content-Type: application/json" \
+ -d '{"task": "Find the top 3 trending repos on GitHub today"}'
+```
+
+```bash Poll status until completed | failed | cancelled (replace RUN_ID)
+curl https://api.browser-use.com/api/v4/runs/RUN_ID/status \
+ -H "X-Browser-Use-API-Key: bu_your_key_here"
+```
+
+```bash Fetch the full run once it's terminal
+curl https://api.browser-use.com/api/v4/runs/RUN_ID \
+ -H "X-Browser-Use-API-Key: bu_your_key_here"
+```
+
+## Sessions and follow-ups
+
+A run belongs to a session (a conversation). Send a follow-up message to a session's queue — it runs as the next turn, or immediately with `interrupt: true`:
+
+```bash Queue a follow-up (replace SESSION_ID)
+curl -X POST https://api.browser-use.com/api/v4/sessions/SESSION_ID/queue \
+ -H "X-Browser-Use-API-Key: bu_your_key_here" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "Now open the top result", "interrupt": false}'
+```
+
+## SDKs
+
+The [Cloud SDK](https://docs.browser-use.com/cloud/sdk) wraps this loop — `runs.create()` then `runs.waitForCompletion()` / `runs.wait_for_completion()` — for TypeScript and Python.
+
+
# API Reference
Source: https://docs.browser-use.com/cloud/api-reference
@@ -2990,6 +4801,16 @@ Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/sett
https://api.browser-use.com/api/v3
```
+## OpenAPI spec
+
+The full API surface is published as a machine-readable OpenAPI 3.1 spec — use it to generate typed clients or validate payloads:
+
+```
+https://docs.browser-use.com/openapi.json
+```
+
+Also at [/cloud/openapi/v3.json](https://docs.browser-use.com/cloud/openapi/v3.json). Legacy v2 spec: [/cloud/openapi/v2.json](https://docs.browser-use.com/cloud/openapi/v2.json).
+
## Quick example
```bash Create a session
@@ -3036,6 +4857,8 @@ export BROWSER_USE_API_KEY=your_key
Base URL: `https://api.browser-use.com/api/v2`
+OpenAPI spec: [/cloud/openapi/v2.json](https://docs.browser-use.com/cloud/openapi/v2.json) — legacy; new projects should use [v3](https://docs.browser-use.com/openapi.json).
+
---
Prefer the SDK? See the [Agent (v2) docs](https://docs.browser-use.com/cloud/legacy/agent).
@@ -3047,65 +4870,3 @@ pip install browser-use-sdk
npm install browser-use-sdk
```
-
-## Browser Use Agent Challenge to Get a Free Account
-
-AI agents can create a free Browser Use account autonomously via a challenge-response flow at `https://api.browser-use.com`.
-
-Do this to get an API key (no human required):
-1. `POST https://api.browser-use.com/cloud/signup` — request a challenge.
-
-Request body, optional (include a user email/name if available):
-```json
-{
- "email": "user@example.com",
- "name": "User Name"
-}
-```
-
-Response:
-```json
-{
- "challenge_id": "uuid",
- "challenge_text": "..."
-}
-```
-
-2. Solve the math problem in `challenge_text` — answer as a string with 2 decimal places, e.g. `"144.00"`
-
-3. `POST https://api.browser-use.com/cloud/signup/verify` with `challenge_id` + `answer`.
-
-Request body:
-```json
-{
- "challenge_id": "uuid",
- "answer": "144.00"
-}
-```
-
-Response:
-```json
-{
- "api_key": "bu_..."
-}
-```
-
-4. Use `X-Browser-Use-API-Key: bu_...` on Browser Use Cloud API requests. For example, create a browser session (docs: https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session):
-
-```bash
-curl -X POST https://api.browser-use.com/api/v3/browsers \
- -H "X-Browser-Use-API-Key: bu_..." \
- -H "Content-Type: application/json" \
- -d '{}'
-```
-
-To let a human claim the account later: `POST https://api.browser-use.com/cloud/signup/claim` with `X-Browser-Use-API-Key: bu_...`.
-
-Response:
-```json
-{
- "claim_url": "https://..."
-}
-```
-
-The claim URL is valid for 1 hour.
diff --git a/docs/cloud/llms.txt b/docs/cloud/llms.txt
index 8b1c30c10..163bdb756 100644
--- a/docs/cloud/llms.txt
+++ b/docs/cloud/llms.txt
@@ -5,7 +5,7 @@
- Dashboard: https://cloud.browser-use.com
- Create API key: https://cloud.browser-use.com/settings?tab=api-keys&new=1
- Docs: https://docs.browser-use.com
-- OpenAPI spec (v3): https://docs.browser-use.com/cloud/openapi/v3.json
+- OpenAPI spec (v3): https://docs.browser-use.com/openapi.json (also at /cloud/openapi/v3.json; legacy v2: /cloud/openapi/v2.json)
- Chat UI example: https://docs.browser-use.com/cloud/tutorials/chat-ui — Full end-to-end example with live browser, streaming, auth. Best starting point to build a prototype.
- Open-source repo: https://github.com/browser-use/browser-use — The open-source Python library. Note: the open-source API is different from the Cloud SDK. If you want the easiest path to production with managed infrastructure, use the Cloud SDK below.
@@ -22,12 +22,16 @@ export BROWSER_USE_API_KEY=bu_your_key_here
## Get Started
+- [Introduction](https://docs.browser-use.com/cloud/introduction): AI browser agents that run on stealth cloud browsers — one API key, driven as much or as little as you want.
+- [Open source vs Cloud](https://docs.browser-use.com/cloud/open-source-vs-cloud): The library and the cloud are different products that combine. Here's which one you want.
- [Quick start](https://docs.browser-use.com/cloud/quickstart): State-of-the-art AI browser automation with stealth browsers, CAPTCHA solving, residential proxies, and managed infrastructure.
-- [Agent Sign Up for Browser Use](https://docs.browser-use.com/cloud/agent-signup): How an AI agent can complete the Browser Use agent challenge to get a free account and API key.
+- [Pricing & free tier](https://docs.browser-use.com/cloud/pricing): Browser Use Cloud plans, the free tier (no card required), and every usage-based rate.
- [Prompt for Vibecoders](https://docs.browser-use.com/cloud/vibecoding): Complete Cloud SDK reference for AI coding agents.
## Agent
+- [Overview](https://docs.browser-use.com/cloud/agent/overview): The hosted agent takes a task in plain language and drives a stealth browser until it's done.
- [Introduction](https://docs.browser-use.com/cloud/agent/quickstart): Easiest way to automate the web. Tell this agent in natural language what it should do, and it can interact with the web like a human.
+- [Sessions](https://docs.browser-use.com/cloud/agent/sessions): One cloud browser plus the tasks an agent runs inside it.
- [Models](https://docs.browser-use.com/cloud/agent/models): Choose the right model for your task.
- [Structured output](https://docs.browser-use.com/cloud/agent/structured-output): Get validated, typed data back from agent tasks.
- [Follow-up tasks](https://docs.browser-use.com/cloud/agent/follow-up-tasks): Run multiple tasks in the same browser session.
@@ -37,27 +41,44 @@ export BROWSER_USE_API_KEY=bu_your_key_here
- [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop): Let a human interact with the live browser while the agent is running. Useful for approvals, payments, complex auth flows, or reviewing agent work before continuing.
## Browser
-- [Introduction Stealth](https://docs.browser-use.com/cloud/browser/stealth): Best stealth on the planet. We fork Chromium to give agents access to all websites.
+- [Overview](https://docs.browser-use.com/cloud/browser/overview): Remote stealth browsers you control over CDP. What they are and when to use one.
+- [Create a browser session](https://docs.browser-use.com/cloud/browser/create): Every way to start a cloud browser: SDK, REST, or a single WebSocket URL, with all parameters and the response schema.
+- [Manage browser sessions](https://docs.browser-use.com/cloud/browser/sessions): Session lifecycle: states, timeouts, stopping, disconnect behavior, and what you're billed for.
+- [Stealth](https://docs.browser-use.com/cloud/browser/stealth): Best stealth on the planet. We fork Chromium to give agents access to all websites.
+- [CAPTCHA Solving](https://docs.browser-use.com/cloud/browser/captcha): Browser Use remote browsers solve CAPTCHAs automatically, on by default, on every plan.
- [Proxies](https://docs.browser-use.com/cloud/browser/proxies): Residential proxies in 195+ countries. On by default.
+- [Screenshots](https://docs.browser-use.com/cloud/browser/screenshots): Take viewport and full-page screenshots from a cloud browser session, and control where they're saved.
- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview): Watch the agent's browser in real time. Embed it in your app.
-- [Playwright, Puppeteer, Selenium](https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium): Connect your automation framework to Browser Use's stealth infrastructure via CDP.
+- [Cloud browser + open source agent](https://docs.browser-use.com/cloud/browser/open-source-agent): Run the open-source Browser Use agent on a cloud stealth browser. Your code, our infrastructure.
+
+## Automation frameworks
+- [Playwright](https://docs.browser-use.com/cloud/browser/playwright): Connect Playwright to a remote stealth browser over CDP — Python and TypeScript.
+- [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer): Connect Puppeteer to a remote stealth browser with browserWSEndpoint.
+- [Selenium](https://docs.browser-use.com/cloud/browser/selenium): Run Selenium-style automation on Browser Use's stealth browsers — and why to bridge through CDP.
## Authentication
- [Profiles](https://docs.browser-use.com/cloud/guides/authentication): Persistent browser state — cookies, localStorage, saved passwords. Login once, reuse across sessions.
-- [Sync local and cloud cookies](https://docs.browser-use.com/cloud/guides/profile-sync): Sync your local browser cookies to the cloud — instantly authenticate without managing credentials.
+- [Profiles / Cookie sync](https://docs.browser-use.com/cloud/guides/profile-sync): Profiles carry cookies and login state across sessions — sync them from your local browser or reuse them in the cloud.
- [2FA](https://docs.browser-use.com/cloud/guides/2fa): Best practices for handling two-factor authentication in automated browser sessions.
## More
- [FAQ](https://docs.browser-use.com/cloud/faq): Common questions and solutions.
+## Platform features
+- [Webhooks](https://docs.browser-use.com/cloud/guides/webhooks): Receive real-time notifications when tasks complete. Configure webhook endpoints for async task monitoring.
+- [x402 (pay-per-request)](https://docs.browser-use.com/cloud/guides/x402): Pay for Browser Use Cloud with crypto (USDC on Base). ~30 seconds from wallet to first request.
+
## Integrations
-- [OpenClaw](https://docs.browser-use.com/cloud/tutorials/integrations/openclaw): Give OpenClaw agents browser automation with Browser Use — via CDP or the CLI skill.
- [MCP Server](https://docs.browser-use.com/cloud/guides/mcp-server): Run browser automation tasks from your AI coding assistant. Connect to Claude, Cursor, Windsurf, or any MCP client.
-- [Webhooks](https://docs.browser-use.com/cloud/guides/webhooks): Receive real-time notifications when tasks complete. Configure webhook endpoints for async task monitoring.
+- [Claude Code](https://docs.browser-use.com/cloud/tutorials/integrations/claude-code): Give Claude Code cloud browser automation with Browser Use.
+- [Claude Managed Agents](https://docs.browser-use.com/cloud/tutorials/integrations/claude-managed-agents): Give Anthropic's Claude Managed Agents a stealth cloud browser via the Browser Use CLI.
+- [OpenClaw](https://docs.browser-use.com/cloud/tutorials/integrations/openclaw): Give OpenClaw agents browser automation with Browser Use — via CDP or the CLI skill.
+- [Hermes Agent](https://docs.browser-use.com/cloud/tutorials/integrations/hermes-agent): Give Hermes Agent cloud browser automation with Browser Use.
- [n8n](https://docs.browser-use.com/cloud/tutorials/integrations/n8n): Use Browser Use as an HTTP node in n8n workflows.
## Tutorials
- [Chat UI](https://docs.browser-use.com/cloud/tutorials/chat-ui): Full end-to-end example. Build a chat UI with live browser preview, follow-up tasks, recording, and streaming messages.
+- [Agent Sign Up for Browser Use](https://docs.browser-use.com/cloud/agent-signup): How the Browser Use agent challenge lets an AI agent create a free account and API key.
- [Grow Therapy provider search](https://docs.browser-use.com/cloud/tutorials/grow-therapy-compare): Search Grow Therapy for therapists by location, insurance, and specialty — with cached reruns.
## Legacy (v2)
@@ -67,70 +88,12 @@ export BROWSER_USE_API_KEY=bu_your_key_here
- [1Password & 2FA](https://docs.browser-use.com/cloud/guides/1password): Auto-fill passwords and TOTP codes from 1Password during agent tasks.
- [Secrets](https://docs.browser-use.com/cloud/guides/secrets): Pass domain-scoped credentials to the agent securely.
+## API v4
+- [API Reference](https://docs.browser-use.com/cloud/api-v4-overview): Authenticate and start using the Browser Use API v4 — the current REST API for long-horizon agents.
+
## API v3
- [API Reference](https://docs.browser-use.com/cloud/api-reference): Authenticate and start using the Browser Use REST API.
## API v2
- [API key](https://docs.browser-use.com/cloud/api-v2-overview): Set your API key to access the Browser Use v2 REST API.
-## Browser Use Agent Challenge to Get a Free Account
-
-AI agents can create a free Browser Use account autonomously via a challenge-response flow at `https://api.browser-use.com`.
-
-Do this to get an API key (no human required):
-1. `POST https://api.browser-use.com/cloud/signup` — request a challenge.
-
-Request body, optional (include a user email/name if available):
-```json
-{
- "email": "user@example.com",
- "name": "User Name"
-}
-```
-
-Response:
-```json
-{
- "challenge_id": "uuid",
- "challenge_text": "..."
-}
-```
-
-2. Solve the math problem in `challenge_text` — answer as a string with 2 decimal places, e.g. `"144.00"`
-
-3. `POST https://api.browser-use.com/cloud/signup/verify` with `challenge_id` + `answer`.
-
-Request body:
-```json
-{
- "challenge_id": "uuid",
- "answer": "144.00"
-}
-```
-
-Response:
-```json
-{
- "api_key": "bu_..."
-}
-```
-
-4. Use `X-Browser-Use-API-Key: bu_...` on Browser Use Cloud API requests. For example, create a browser session (docs: https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session):
-
-```bash
-curl -X POST https://api.browser-use.com/api/v3/browsers \
- -H "X-Browser-Use-API-Key: bu_..." \
- -H "Content-Type: application/json" \
- -d '{}'
-```
-
-To let a human claim the account later: `POST https://api.browser-use.com/cloud/signup/claim` with `X-Browser-Use-API-Key: bu_...`.
-
-Response:
-```json
-{
- "claim_url": "https://..."
-}
-```
-
-The claim URL is valid for 1 hour.
diff --git a/docs/cloud/open-source-vs-cloud.mdx b/docs/cloud/open-source-vs-cloud.mdx
new file mode 100644
index 000000000..baca62942
--- /dev/null
+++ b/docs/cloud/open-source-vs-cloud.mdx
@@ -0,0 +1,34 @@
+---
+title: Open source vs Cloud
+description: "The library and the cloud are different products that combine. Here's which one you want."
+icon: code-compare
+---
+
+Browser Use is two things with one name. The confusion is common enough to deserve its own page.
+
+**The [open-source library](/open-source/introduction)** (`pip install browser-use`) is an agent framework that runs on your machine. You bring your own LLM key, it launches a local Chromium, and nothing leaves your infrastructure. Free, Apache-licensed, yours.
+
+**Browser Use Cloud** (this documentation) is a paid API with two services: [stealth cloud browsers](/cloud/browser/overview) you can drive with any framework, and a [hosted agent](/cloud/agent/overview) that runs tasks for you, no library install required.
+
+## Which do you want?
+
+| You want to... | Use |
+|---|---|
+| Run an agent locally, free, with your own LLM keys | Open source library |
+| Keep your local agent but stop getting blocked by websites | Library + [cloud browser](/cloud/browser/open-source-agent) |
+| Drive stealth browsers with existing Playwright/Puppeteer scripts | Cloud [Browser](/cloud/browser/overview) |
+| Send a task and get a result, zero infrastructure | Cloud [Agent](/cloud/agent/overview) |
+
+## Common questions
+
+**Do I need an API key to use the library?**
+No. The library needs an LLM provider key (OpenAI, Anthropic, Ollama for fully local). A Browser Use API key is only needed for cloud features.
+
+**Does the library have stealth or CAPTCHA solving?**
+No. Those are properties of the cloud browsers. The bridge is one parameter: point the library's `Browser` at a [cloud browser session](/cloud/browser/open-source-agent).
+
+**Is the cloud agent the same agent as the library?**
+The cloud agent is the hosted, managed version, with the same task-in, result-out model plus cloud-only features like [structured output](/cloud/agent/structured-output), [workspaces](/cloud/agent/workspaces), and [human-in-the-loop](/cloud/agent/human-in-the-loop).
+
+**Can I self-host the cloud?**
+The library is the self-hosted option: your machines, your browsers, your keys. The stealth browser fleet and hosted agent are not self-hostable.
diff --git a/docs/cloud/openapi/v3.json b/docs/cloud/openapi/v3.json
index a0b721758..6c405728d 100644
--- a/docs/cloud/openapi/v3.json
+++ b/docs/cloud/openapi/v3.json
@@ -2667,6 +2667,200 @@
}
}
}
+ },
+ "/search": {
+ "post": {
+ "tags": [
+ "Search"
+ ],
+ "summary": "Search the web",
+ "description": "Run a web search and get back a ranked list of LLM-optimized results. Each successful request is billed to your project balance.",
+ "operationId": "search",
+ "security": [
+ {
+ "APIKeyHeader": []
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Standardized, ranked search results.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Missing or invalid `query`.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchError"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Missing or invalid API key.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchError"
+ }
+ }
+ }
+ },
+ "402": {
+ "description": "Insufficient balance — add credits to continue.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchError"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "Rate limit exceeded — retry later.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchError"
+ }
+ }
+ }
+ },
+ "502": {
+ "description": "The search request failed — retry later.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchError"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "Authentication or billing is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SearchError"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/fetch": {
+ "post": {
+ "tags": [
+ "Fetch"
+ ],
+ "summary": "Fetch a URL",
+ "description": "Execute an HTTP request through Browser Use's proxy infrastructure with Chrome TLS fingerprinting, so the request looks like genuine browser traffic.",
+ "operationId": "fetch",
+ "security": [
+ {
+ "APIKeyHeader": []
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The fetched response.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Missing or invalid request (e.g. no `url`).",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchError"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Missing or invalid API key.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchError"
+ }
+ }
+ }
+ },
+ "402": {
+ "description": "Insufficient balance.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchError"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Request blocked (e.g. SSRF protection: private/internal address).",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchError"
+ }
+ }
+ }
+ },
+ "502": {
+ "description": "The upstream request failed.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchError"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "Authentication or balance service temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/FetchError"
+ }
+ }
+ }
+ }
+ }
+ }
}
},
"components": {
@@ -5476,6 +5670,269 @@
"type": "object",
"title": "RunTaskRequest",
"description": "Create a new session, dispatch a task, or both.\n\n- **No `sessionId` + no `task`**: creates an idle session (useful for uploading files before running a task).\n- **No `sessionId` + `task`**: creates a new session and immediately runs the task.\n- **`sessionId` + `task`**: dispatches the task to an existing idle session.\n- **`sessionId` + no `task`**: returns 422 — a task is required when targeting an existing session."
+ },
+ "SearchRequest": {
+ "type": "object",
+ "required": [
+ "query"
+ ],
+ "properties": {
+ "query": {
+ "type": "string",
+ "minLength": 1,
+ "description": "The search query in natural language. Returns a ranked set of relevant web results.",
+ "example": "latest research on protein folding"
+ }
+ }
+ },
+ "SearchResult": {
+ "type": "object",
+ "required": [
+ "url",
+ "content"
+ ],
+ "properties": {
+ "title": {
+ "type": "string",
+ "description": "Title of the source. Omitted when the source does not provide one.",
+ "example": "An Introduction to Protein Folding"
+ },
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Canonical URL of the source.",
+ "example": "https://example.com/protein-folding"
+ },
+ "published_date": {
+ "type": "string",
+ "description": "Publication date of the source (YYYY-MM-DD). Omitted when the source does not provide one.",
+ "example": "2026-04-08"
+ },
+ "content": {
+ "type": "string",
+ "description": "Relevant excerpts from the source, joined into a single markdown string and optimized for LLM consumption.",
+ "example": "# An Introduction to Protein Folding\n\n..."
+ }
+ }
+ },
+ "SearchResponse": {
+ "type": "object",
+ "required": [
+ "results"
+ ],
+ "properties": {
+ "results": {
+ "type": "array",
+ "description": "Ranked list of web results, most relevant first.",
+ "items": {
+ "$ref": "#/components/schemas/SearchResult"
+ }
+ }
+ }
+ },
+ "SearchError": {
+ "type": "object",
+ "required": [
+ "error"
+ ],
+ "properties": {
+ "error": {
+ "type": "string",
+ "description": "A generic, provider-agnostic error message.",
+ "example": "insufficient balance"
+ }
+ }
+ },
+ "FetchRetryConfig": {
+ "type": "object",
+ "description": "Retry behavior for failed requests.",
+ "properties": {
+ "count": {
+ "type": "integer",
+ "description": "Number of retry attempts.",
+ "default": 3
+ },
+ "on_status": {
+ "type": "array",
+ "items": {
+ "type": "integer"
+ },
+ "description": "Status codes that trigger a retry.",
+ "default": [
+ 500,
+ 502,
+ 503,
+ 504
+ ]
+ },
+ "backoff_ms": {
+ "type": "integer",
+ "description": "Initial backoff in milliseconds (exponential).",
+ "default": 100
+ }
+ }
+ },
+ "FetchRequest": {
+ "type": "object",
+ "required": [
+ "url"
+ ],
+ "properties": {
+ "url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Target URL.",
+ "example": "https://example.com"
+ },
+ "method": {
+ "type": "string",
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE",
+ "HEAD",
+ "OPTIONS"
+ ],
+ "default": "GET",
+ "description": "HTTP method."
+ },
+ "headers": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Additional HTTP headers."
+ },
+ "body": {
+ "type": "string",
+ "description": "Request body as text."
+ },
+ "body_base64": {
+ "type": "string",
+ "description": "Request body as base64, for binary content."
+ },
+ "content_type": {
+ "type": "string",
+ "description": "Override the Content-Type header."
+ },
+ "output_format": {
+ "type": "string",
+ "enum": [
+ "raw",
+ "markdown",
+ "structured",
+ "simplified"
+ ],
+ "default": "raw",
+ "description": "How to format the response body. `raw` returns the page unchanged; `markdown` returns clean readable text; `structured` returns a parsed object (title, links, headings, tables); `simplified` strips boilerplate."
+ },
+ "follow_redirects": {
+ "type": "boolean",
+ "default": true,
+ "description": "Follow HTTP redirects."
+ },
+ "max_redirects": {
+ "type": "integer",
+ "default": 10,
+ "description": "Maximum redirects to follow."
+ },
+ "timeout_ms": {
+ "type": "integer",
+ "default": 30000,
+ "maximum": 120000,
+ "description": "Request timeout in milliseconds."
+ },
+ "session_id": {
+ "type": "string",
+ "description": "Session ID. Requests sharing a session persist cookies and the proxy IP across calls."
+ },
+ "proxy_country": {
+ "type": "string",
+ "default": "US",
+ "description": "ISO 3166-1 alpha-2 country code for proxy routing (e.g. `DE`)."
+ },
+ "retry": {
+ "$ref": "#/components/schemas/FetchRetryConfig"
+ },
+ "insecure_skip_verify": {
+ "type": "boolean",
+ "default": false,
+ "description": "Skip TLS certificate verification."
+ }
+ }
+ },
+ "FetchResponse": {
+ "type": "object",
+ "properties": {
+ "status_code": {
+ "type": "integer",
+ "description": "HTTP status code."
+ },
+ "status": {
+ "type": "string",
+ "description": "Full status string (e.g. \"200 OK\")."
+ },
+ "headers": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "description": "Response headers. Each value is a list of strings."
+ },
+ "body": {
+ "type": "string",
+ "description": "Response body as text."
+ },
+ "body_base64": {
+ "type": "string",
+ "description": "Response body as base64, when binary."
+ },
+ "is_binary": {
+ "type": "boolean",
+ "description": "Whether the response is binary content."
+ },
+ "final_url": {
+ "type": "string",
+ "description": "Final URL after redirects."
+ },
+ "redirect_count": {
+ "type": "integer",
+ "description": "Number of redirects followed."
+ },
+ "protocol": {
+ "type": "string",
+ "description": "HTTP protocol version (e.g. \"HTTP/2.0\")."
+ },
+ "error": {
+ "type": "string",
+ "description": "Error message if the request failed."
+ }
+ }
+ },
+ "FetchError": {
+ "type": "object",
+ "required": [
+ "error"
+ ],
+ "properties": {
+ "error": {
+ "type": "string",
+ "description": "Error message."
+ },
+ "code": {
+ "type": "integer",
+ "description": "HTTP status code."
+ },
+ "details": {
+ "type": "string",
+ "description": "Additional error details."
+ }
+ }
}
},
"securitySchemes": {
diff --git a/docs/cloud/pricing.mdx b/docs/cloud/pricing.mdx
new file mode 100644
index 000000000..96b0d27cb
--- /dev/null
+++ b/docs/cloud/pricing.mdx
@@ -0,0 +1,66 @@
+---
+title: Pricing & free tier
+description: "Browser Use Cloud plans, the free tier (no card required), and every usage-based rate."
+icon: credit-card
+---
+
+Browser Use Cloud has a free tier and four paid plans. Usage (browser time, proxy data, agent tokens) is billed on top of the plan. The [pricing page](https://browser-use.com/pricing) is the canonical source; the numbers here are kept in sync with it.
+
+## Free tier
+
+Free, no credit card required. It includes:
+
+- 3 concurrent browser sessions
+- 1 browser profile, 1 team member
+- Basic proxy pool
+- Advanced [stealth](/cloud/browser/stealth), [CAPTCHA solving](/cloud/browser/captcha), and [webhook events](/cloud/guides/webhooks)
+- Community support
+
+Stealth and CAPTCHA solving are on for every tier, including free. They are not paid add-ons.
+
+## Plans
+
+| Plan | Monthly | Included credits | Concurrent sessions | Team members |
+|------|---------|------------------|---------------------|--------------|
+| Free | $0 | — | 3 | 1 |
+| Dev | $29 | $29 | 25 | 5 |
+| Business | $299 | $299 | 200 | Unlimited |
+| Scaleup | $999 | $999 | 500 | Unlimited |
+| Enterprise | Custom | Negotiated | Negotiated | Negotiated |
+
+Annual billing is pay for 10 months, get 12 (Dev $290/yr, Business $2,990/yr, Scaleup $9,990/yr).
+
+The concurrent-session limit is what a `429 Too many concurrent active sessions` error refers to. Stop idle sessions or upgrade the plan to raise it.
+
+## Usage rates
+
+Billed against your plan credits, then charged if you exceed them.
+
+**Browser & proxies**
+- Browser session: $0.02/hour, active time only
+- Proxy bandwidth: $5/GB
+
+**Agent (v3, token-based at 1.2× provider rates)**
+
+| Model | Input / output per 1M tokens |
+|-------|------------------------------|
+| GPT-5.4 Mini | $0.90 / $5.40 |
+| Claude Sonnet 4.6 | $3.60 / $18.00 |
+| Claude Opus 4.6 / 4.7 | $6.00 / $30.00 |
+
+When you [bring your own LLM](/cloud/agent/models), those tokens go to your own provider instead.
+
+## Tracking spend
+
+Every browser session object reports its own running cost (`browserCost`, `proxyCost`, `proxyUsedMb`), so spend is inspectable per session. [Stop sessions](/cloud/browser/sessions#stopping-a-session) when done — an idle session bills until it stops or [times out](/cloud/browser/sessions#timeouts).
+
+## The open-source library is free
+
+The [library](/open-source/introduction) has no Browser Use charges — you pay only your own LLM provider. Cloud rates apply when you use cloud browsers or the hosted agent. See [Open source vs Cloud](/cloud/open-source-vs-cloud).
+
+## Further reading
+
+- [Remote browsers for agents: the Browser Use free tier](https://browser-use.com/posts/free-tier-announcement)
+- [How we made cloud browsers 3x cheaper and faster](https://browser-use.com/posts/firecracker-browser-infra)
+
+{/* TEAM REVIEW: keep this table in sync with browser-use.com/pricing. The v2 agent (per-step from $0.006, task init $0.01) is legacy — omitted here; add a legacy note if v2 users need it. */}
diff --git a/docs/cloud/quickstart.mdx b/docs/cloud/quickstart.mdx
index b461a5ffc..b0789dd6e 100644
--- a/docs/cloud/quickstart.mdx
+++ b/docs/cloud/quickstart.mdx
@@ -9,6 +9,9 @@ icon: rocket
+
+
+ {/* Live browser view — liveUrl available from session creation */}
+
+
+
+Browser Use Cloud lands **81%** — ahead of every other cloud browser, and far above a plain headless browser (2%).
+
+We get there by forking Chromium rather than patching detection signals with stealth plugins, so the signals never appear in the first place. [Here's why that approach holds up as anti-bot systems tighten](https://browser-use.com/posts/bot-detection).
+
## What's included
-Every cloud browser session runs in a hardened Chromium fork with stealth enabled by default — no configuration needed.
+Every cloud browser session runs in a hardened Chromium fork with stealth enabled by default — no configuration needed. [Create a browser session](https://docs.browser-use.com/cloud/browser/create) and it is already on.
- **Anti-detect browser fingerprinting** — Canvas, WebGL, fonts, navigator, and other browser fingerprints are randomized per session to appear as a real user. Passes CreepJS, BrowserLeaks, and other fingerprint detectors.
- **Ad and cookie banner blocking** — Banners are dismissed automatically so the agent sees clean pages and executes faster.
- **Cloudflare / anti-bot bypass** — Works on sites protected by Cloudflare, PerimeterX, and other bot detection services.
+Stealth keeps most challenges from ever appearing. When one does, it is solved automatically — see [CAPTCHA solving](https://docs.browser-use.com/cloud/browser/captcha) for per-vendor success rates.
+
## Residential proxies
Residential proxies are enabled by default across 195+ countries. This makes browser sessions appear as real users from the target geography. See [Proxies](https://docs.browser-use.com/cloud/browser/proxies) for details on geo-targeting and custom proxy configuration.
+## Further reading
+
+- [Benchmarks](https://browser-use.com/benchmarks) — 84.8% on BrowserBench and 81% bypass on high-security sites, against other providers
+- [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark)
+- [Browser agent bot detection is about to change](https://browser-use.com/posts/bot-detection)
+- [Stealth Browser Infrastructure](https://browser-use.com/posts/browser-infra)
+
+
+# CAPTCHA Solving
+Source: https://docs.browser-use.com/cloud/browser/captcha
+
+
+Browser Use remote browsers have **automatic CAPTCHA solving** built in. There is nothing to configure — on the browser, the attached agent, or your automation library (Playwright, Puppeteer, Selenium). It is on by default on every plan, including the [free tier](https://docs.browser-use.com/cloud/pricing).
+
+The best defense is not tripping a challenge in the first place — that is what [stealth](https://docs.browser-use.com/cloud/browser/stealth) handles (anti-fingerprinting and bot-detection bypass). This page covers what happens when a CAPTCHA or anti-bot system appears anyway: we solve it, and we lead the field on success rate.
+
+## Success rate by vendor
+
+Across the anti-bot and CAPTCHA systems agents hit most, Browser Use Cloud has the **highest overall success rate at 81%** — and the best against **Cloudflare (93%)** and **PerimeterX (81%)**.
+
+| Protection | Browser Use Cloud |
+| --- | --- |
+| Overall | **81%** |
+| Cloudflare | **93%** |
+| PerimeterX | **81%** |
+| Akamai | 85% |
+| DataDome | 69% |
+| reCAPTCHA | 80% |
+
+
+
+
+
+Full methodology in [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark).
+
+## Supported CAPTCHA types
+
+These are the interactive CAPTCHA widgets solved automatically, distinct from the anti-bot systems above (Cloudflare, DataDome, PerimeterX, Akamai) that gate a site before a widget ever appears:
+
+| CAPTCHA type | Solved automatically |
+| --- | --- |
+| reCAPTCHA v2 (checkbox / image challenge) | Yes |
+| reCAPTCHA v3 (score-based) | Yes |
+| hCaptcha | Yes |
+| Cloudflare Turnstile | Yes |
+
+All are handled on by default — no `captcha_type` parameter or per-widget configuration.
+
+## Get started
+
+There is nothing to turn on. CAPTCHA solving comes with every session. Start one:
+
+SDK, REST, or a single WebSocket URL.
+Playwright, Puppeteer, or Selenium over CDP.
+What the hardened Chromium fork does.
+Residential IPs in 195+ countries, on by default.
+
+## FAQ
+
+**Does the open-source library solve CAPTCHAs?**
+
+Without remote browsers, [open-source](https://github.com/browser-use/browser-use) agents have no stealth or CAPTCHA solving. Giving your agent stealth is easy: run it on a remote browser with a single parameter. See [Cloud browser + open source agent](https://docs.browser-use.com/cloud/browser/open-source-agent).
+
+**Can I use a third-party CAPTCHA solver?**
+
+No, we do not support third-party CAPTCHA solver plugins on the browser. If your CAPTCHAs are not being solved properly, reach out and we will look into it.
+
+**Do I need to enable anything for CAPTCHA solving?**
+
+No. Remote browsers solve CAPTCHAs for you automatically.
+
+## Further reading
+
+- [Prove you are a robot: CAPTCHAs for agents](https://browser-use.com/posts/prove-you-are-a-robot)
+- [Browser agent bot detection is about to change](https://browser-use.com/posts/bot-detection)
+
# Proxies
Source: https://docs.browser-use.com/cloud/browser/proxies
@@ -1080,12 +1682,12 @@ from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
browser = await client.browsers.create(
-custom_proxy={
- "host": "proxy.example.com",
- "port": 8080,
- "username": "user",
- "password": "pass",
-},
+ custom_proxy={
+ "host": "proxy.example.com",
+ "port": 8080,
+ "username": "user",
+ "password": "pass",
+ },
)
```
```typescript TypeScript
@@ -1094,14 +1696,119 @@ import { BrowserUse } from "browser-use-sdk/v3";
const client = new BrowserUse();
const browser = await client.browsers.create({
customProxy: {
-host: "proxy.example.com",
-port: 8080,
-username: "user",
-password: "pass",
+ host: "proxy.example.com",
+ port: 8080,
+ username: "user",
+ password: "pass",
},
});
```
+## Blocked? Get a fresh IP
+
+Browser Use does not rotate the IP within a running session. When a site starts blocking you, stop the session and create a new one — each session gets a fresh residential IP from the country pool automatically.
+
+```python Python
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+client = AsyncBrowserUse()
+
+async def with_fresh_ip(country="us", profile_id=None):
+ # Stop-and-recreate is how you get a new IP; reattach a profile to keep login state.
+ browser = await client.browsers.create(proxy_country_code=country, profile_id=profile_id)
+ return browser
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v3";
+
+const client = new BrowserUse();
+
+async function withFreshIp(country = "us", profileId?: string) {
+ // Stop-and-recreate is how you get a new IP; reattach a profile to keep login state.
+ return client.browsers.create({ proxyCountryCode: country, profileId });
+}
+```
+
+- **New session = new IP.** Recreating the browser is the supported way to rotate.
+- **Keep your login across the rotation** by passing the same [`profile_id`](https://docs.browser-use.com/cloud/guides/authentication) — the fresh IP loads the saved cookies and localStorage.
+- **Switch country** (`proxy_country_code`) to leave a blocked regional pool entirely.
+- **Custom proxies** can rotate per request on their side — use the `custom_proxy` config above with a rotating endpoint.
+
+## Further reading
+
+- [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark) — how proxy quality affects bypass rates
+
+
+# Screenshots
+Source: https://docs.browser-use.com/cloud/browser/screenshots
+
+
+A cloud browser session is a normal CDP endpoint, so screenshots work the way your framework takes them, and they save wherever your code runs.
+
+## Where screenshots are saved
+
+The most-asked question first: screenshots taken through Playwright or Puppeteer are written by *your* code, to a path *you* choose. Nothing is stored on the session unless you enable [recording](https://docs.browser-use.com/cloud/browser/sessions#recordings-and-downloads).
+
+```python Python
+from playwright.async_api import async_playwright
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+client = AsyncBrowserUse()
+browser = await client.browsers.create()
+
+async with async_playwright() as p:
+ pw = await p.chromium.connect_over_cdp(browser.cdp_url)
+ page = pw.contexts[0].pages[0]
+ await page.goto("https://example.com")
+ await page.screenshot(path="shots/example.png") # your machine, your path
+
+await client.browsers.stop(browser.id)
+```
+```typescript TypeScript
+import { chromium } from "playwright";
+import { BrowserUse } from "browser-use-sdk/v3";
+
+const client = new BrowserUse();
+const browser = await client.browsers.create();
+
+const pw = await chromium.connectOverCDP(browser.cdpUrl);
+const page = pw.contexts()[0].pages()[0];
+await page.goto("https://example.com");
+await page.screenshot({ path: "shots/example.png" });
+
+await client.browsers.stop(browser.id);
+```
+
+## Full page, not just the viewport
+
+By default a screenshot captures the visible viewport. For the whole page, top to bottom:
+
+```python
+await page.screenshot(path="full.png", full_page=True)
+```
+
+Playwright stitches the scroll automatically. The result contains page content only, no URL bar or browser chrome, because CDP screenshots capture the rendered page, not the window.
+
+## Resolution
+
+Screenshot dimensions follow the browser's screen size, set at [session creation](https://docs.browser-use.com/cloud/browser/create) with `browserScreenWidth` and `browserScreenHeight` (320–6144 × 320–3456). Set them explicitly if screenshots must match a target resolution:
+
+```python
+browser = await client.browsers.create(browser_screen_width=1920, browser_screen_height=1080)
+```
+
+{/* TEAM REVIEW: document the default screen size when width/height are omitted, and whether recording resolution (1920x1080 reported by users) can differ from screenshot resolution — a user reported 1512x770 screenshots vs 1920x1080 recordings. */}
+
+## Screenshots vs recording
+
+Screenshots are moments; [recording](https://docs.browser-use.com/cloud/browser/sessions#recordings-and-downloads) is the whole session as video (`enableRecording: true` at create, `recordingUrl` after stop). For debugging agent behavior, recording is usually what you want; for artifacts and QA evidence, screenshots.
+
+## From agent tasks
+
+Ask the agent to take screenshots as part of a task and collect them from the run's [workspace files](https://docs.browser-use.com/cloud/agent/workspaces).
+
+{/* TEAM REVIEW: add the exact API for retrieving agent step screenshots (the v1 /screenshots endpoint users reference) and note whether those images carry element highlight overlays — users ask for unmarked versions. */}
+
# Live preview & recording
Source: https://docs.browser-use.com/cloud/browser/live-preview
@@ -1194,14 +1901,14 @@ from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"Check how many GitHub stars browser-use has",
-enable_recording=True,
+ "Check how many GitHub stars browser-use has",
+ enable_recording=True,
)
# Waits up to 15s for recording to be ready. Returns [] if no browser was opened.
urls = await client.sessions.wait_for_recording(result.id)
for url in urls:
-print(url) # presigned MP4 download URL
+ print(url) # presigned MP4 download URL
```
```typescript TypeScript
import { BrowserUse } from "browser-use-sdk/v3";
@@ -1242,29 +1949,32 @@ console.log(stopped.recordingUrl); // presigned MP4 download URL
-# Playwright, Puppeteer, Selenium
-Source: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium
+# Playwright
+Source: https://docs.browser-use.com/cloud/browser/playwright
+
+Run your Playwright scripts on Browser Use's cloud browsers. Every session runs in a [hardened Chromium fork](https://docs.browser-use.com/cloud/browser/stealth) with stealth, anti-fingerprinting, and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) enabled by default — no configuration needed.
-Every session runs in a [hardened Chromium fork](https://docs.browser-use.com/cloud/browser/stealth) with stealth, anti-fingerprinting, and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) enabled by default — no configuration needed.
+When to use this:
+- You have existing Playwright scripts and want to run them on stealth infrastructure
+- You need pixel-perfect control (screenshots, specific click coordinates, form filling)
+- You want to combine agent tasks with manual browser automation
## Option 1: WebSocket URL (no SDK)
Connect with a single URL. All configuration is passed as query parameters.
-### Playwright
-
```python Python
from playwright.async_api import async_playwright
WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us"
async with async_playwright() as p:
-browser = await p.chromium.connect_over_cdp(WSS_URL)
-page = browser.contexts[0].pages[0]
-await page.goto("https://example.com")
-print(await page.title())
-await browser.close()
+ browser = await p.chromium.connect_over_cdp(WSS_URL)
+ page = browser.contexts[0].pages[0]
+ await page.goto("https://example.com")
+ print(await page.title())
+ await browser.close()
# Browser is automatically stopped when the WebSocket disconnects
```
```typescript TypeScript
@@ -1280,40 +1990,7 @@ await browser.close();
// Browser is automatically stopped when the WebSocket disconnects
```
-### Puppeteer
-
-```typescript
-import puppeteer from "puppeteer-core";
-
-const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";
-
-const browser = await puppeteer.connect({ browserWSEndpoint: WSS_URL });
-const [page] = await browser.pages();
-await page.goto("https://example.com");
-console.log(await page.title());
-await browser.close();
-```
-
-### Selenium
-
-Selenium requires a local WebSocket proxy to connect to Browser Use's remote CDP endpoint. Use [selenium-wire](https://github.com/wkeeling/selenium-wire) or connect through Playwright's CDP bridge instead:
-
-```python
-from playwright.sync_api import sync_playwright
-
-WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us"
-
-with sync_playwright() as p:
-browser = p.chromium.connect_over_cdp(WSS_URL)
-page = browser.contexts[0].pages[0]
-page.goto("https://example.com")
-print(page.title())
-browser.close()
-```
-
- Selenium's `debugger_address` only supports local `host:port` connections. For remote CDP over WebSocket, use Playwright or Puppeteer instead.
-
-## Query parameters
+### Query parameters
| Parameter | Type | Description |
|-----------|------|-------------|
@@ -1326,9 +2003,7 @@ browser.close()
## Option 2: SDK
-Create a browser via the SDK, get a `cdp_url`, and connect with Playwright or Puppeteer.
-
-### Playwright
+Create a browser via the SDK, get a `cdp_url`, and connect. The SDK also gives you a `live_url` to [watch or embed the session](https://docs.browser-use.com/cloud/browser/live-preview).
```python Python
from browser_use_sdk.v3 import AsyncBrowserUse
@@ -1340,11 +2015,11 @@ print(browser.cdp_url) # https://uuid.cdpN.browser-use.com
print(browser.live_url) # https://live.browser-use.com?wss=...
async with async_playwright() as p:
-pw_browser = await p.chromium.connect_over_cdp(browser.cdp_url)
-page = pw_browser.contexts[0].pages[0]
-await page.goto("https://example.com")
-print(await page.title())
-await pw_browser.close()
+ pw_browser = await p.chromium.connect_over_cdp(browser.cdp_url)
+ page = pw_browser.contexts[0].pages[0]
+ await page.goto("https://example.com")
+ print(await page.title())
+ await pw_browser.close()
await client.browsers.stop(browser.id)
```
@@ -1366,68 +2041,401 @@ await pwBrowser.close();
await client.browsers.stop(browser.id);
```
-### Puppeteer
+### Create response
-```typescript
-import { BrowserUse } from "browser-use-sdk/v3";
-import puppeteer from "puppeteer-core";
+`browsers.create()` wraps `POST https://api.browser-use.com/api/v3/browsers`, which returns `201` with:
-const client = new BrowserUse();
-const browser = await client.browsers.create();
+```json
+{
+ "id": "0d5f16f3-96cc-4d5f-a5a4-4a4d3b5f9d2e",
+ "status": "active",
+ "liveUrl": "https://live.browser-use.com?wss=...",
+ "cdpUrl": "https://0d5f16f3.cdp1.browser-use.com",
+ "timeoutAt": "2026-07-14T20:15:00Z",
+ "startedAt": "2026-07-14T20:00:00Z",
+ "finishedAt": null,
+ "proxyUsedMb": "0.0",
+ "proxyCost": "0.0",
+ "browserCost": "0.0",
+ "agentSessionId": null,
+ "recordingUrl": null
+}
+```
-// Puppeteer needs the WebSocket URL from /json/version
-const resp = await fetch(`${browser.cdpUrl}/json/version`);
-const { webSocketDebuggerUrl } = await resp.json();
+Field names are camelCase in the REST API and TypeScript SDK (`cdpUrl`, `liveUrl`) and snake_case in the Python SDK (`cdp_url`, `live_url`). `cdpUrl` and `liveUrl` are nullable — check them before connecting.
-const pwBrowser = await puppeteer.connect({ browserWSEndpoint: webSocketDebuggerUrl });
-const [page] = await pwBrowser.pages();
-await page.goto("https://example.com");
-console.log(await page.title());
-await pwBrowser.close();
+### Stopping a session over REST
-await client.browsers.stop(browser.id);
+There is no `POST /browsers/{id}/stop` endpoint. Stopping is an update:
+
+```bash
+curl -X PATCH "https://api.browser-use.com/api/v3/browsers/$SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action": "stop"}'
```
- Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+## Gotchas
+ Use `connect_over_cdp()` / `connectOverCDP()`, **not** `connect()`. Playwright's `connect()` expects a Playwright-protocol server and fails against a CDP endpoint with an opaque `Protocol error (Browser.getVersion)`.
-# Profiles
-Source: https://docs.browser-use.com/cloud/guides/authentication
+- **Reuse the existing context.** The session already has a context and page open — use `browser.contexts[0].pages[0]` instead of `browser.new_context()`, so you keep the stealth fingerprint and any loaded [profile](https://docs.browser-use.com/cloud/browser/playwright#query-parameters).
+- **Closing the connection vs stopping the session.** With the WebSocket URL, disconnecting stops the browser. With the SDK, `pw_browser.close()` only disconnects your client — call `client.browsers.stop(browser.id)` to end the session.
+ Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+
+## See also
+
+- [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer) and [Selenium](https://docs.browser-use.com/cloud/browser/selenium) connections
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — watch the session or embed it in your app
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies) and [stealth](https://docs.browser-use.com/cloud/browser/stealth) configuration
+
+
+# Puppeteer
+Source: https://docs.browser-use.com/cloud/browser/puppeteer
+
+
+Run your Puppeteer scripts on Browser Use's cloud browsers. Every session runs in a [hardened Chromium fork](https://docs.browser-use.com/cloud/browser/stealth) with stealth, anti-fingerprinting, and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) enabled by default — no configuration needed.
+
+When to use this:
+- You have existing Puppeteer scripts and want to run them on stealth infrastructure
+- You want low-level CDP control from Node.js without managing Chrome yourself
+- You want to combine agent tasks with manual browser automation
+
+## Option 1: WebSocket URL (no SDK)
+
+Connect with a single URL. All configuration is passed as query parameters.
+
+```typescript
+import puppeteer from "puppeteer-core";
+
+const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";
+
+const browser = await puppeteer.connect({ browserWSEndpoint: WSS_URL });
+const [page] = await browser.pages();
+await page.goto("https://example.com");
+console.log(await page.title());
+await browser.close();
+// Browser is automatically stopped when the WebSocket disconnects
+```
+
+### Query parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiKey` | `string` | **Required.** Your Browser Use API key. |
+| `proxyCountryCode` | `string` | Proxy country code (e.g. `us`, `de`, `jp`). 195+ countries. |
+| `profileId` | `string` | Load a saved browser profile (cookies, localStorage). |
+| `timeout` | `int` | Session timeout in minutes. Default: 15. Max: 240 (4 hours). |
+| `browserScreenWidth` | `int` | Browser width in pixels. |
+| `browserScreenHeight` | `int` | Browser height in pixels. |
+
+## Option 2: SDK
+
+Create a browser via the SDK, then resolve the WebSocket endpoint. Unlike Playwright, Puppeteer can't connect to an HTTP CDP URL directly — fetch `/json/version` to get the `webSocketDebuggerUrl` first.
+
+```typescript
+import { BrowserUse } from "browser-use-sdk/v3";
+import puppeteer from "puppeteer-core";
+
+const client = new BrowserUse();
+const browser = await client.browsers.create();
+
+// Puppeteer needs the WebSocket URL from /json/version
+const resp = await fetch(`${browser.cdpUrl}/json/version`);
+const { webSocketDebuggerUrl } = await resp.json();
+
+const pptrBrowser = await puppeteer.connect({ browserWSEndpoint: webSocketDebuggerUrl });
+const [page] = await pptrBrowser.pages();
+await page.goto("https://example.com");
+console.log(await page.title());
+await pptrBrowser.close();
+
+await client.browsers.stop(browser.id);
+```
+
+The SDK also gives you a `liveUrl` to [watch or embed the session](https://docs.browser-use.com/cloud/browser/live-preview).
+
+### Create response
+
+`browsers.create()` wraps `POST https://api.browser-use.com/api/v3/browsers`, which returns `201` with:
+
+```json
+{
+ "id": "0d5f16f3-96cc-4d5f-a5a4-4a4d3b5f9d2e",
+ "status": "active",
+ "liveUrl": "https://live.browser-use.com?wss=...",
+ "cdpUrl": "https://0d5f16f3.cdp1.browser-use.com",
+ "timeoutAt": "2026-07-14T20:15:00Z",
+ "startedAt": "2026-07-14T20:00:00Z",
+ "finishedAt": null,
+ "proxyUsedMb": "0.0",
+ "proxyCost": "0.0",
+ "browserCost": "0.0",
+ "agentSessionId": null,
+ "recordingUrl": null
+}
+```
+
+Field names are camelCase in the REST API and TypeScript SDK (`cdpUrl`, `liveUrl`). `cdpUrl` and `liveUrl` are nullable — check them before connecting.
+
+### Stopping a session over REST
+
+There is no `POST /browsers/{id}/stop` endpoint. Stopping is an update:
+
+```bash
+curl -X PATCH "https://api.browser-use.com/api/v3/browsers/$SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action": "stop"}'
+```
+
+## Gotchas
+
+- **Use `puppeteer-core`.** It's the connect-only package — installing full `puppeteer` downloads a local Chromium you'll never use.
+- **`browserWSEndpoint` must be a `ws://`/`wss://` URL.** Passing the SDK's HTTPS `cdpUrl` directly fails; resolve it via `/json/version` as shown above.
+- **Viewport.** Puppeteer applies its own 800×600 default viewport after connecting. Pass `defaultViewport: null` to `puppeteer.connect()` to keep the browser's real window size.
+- **Closing the connection vs stopping the session.** With the WebSocket URL, disconnecting stops the browser. With the SDK, `browser.close()` only disconnects your client — call `client.browsers.stop(browser.id)` to end the session.
+
+ Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+
+## See also
+
+- [Playwright](https://docs.browser-use.com/cloud/browser/playwright) and [Selenium](https://docs.browser-use.com/cloud/browser/selenium) connections
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — watch the session or embed it in your app
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies) and [stealth](https://docs.browser-use.com/cloud/browser/stealth) configuration
+
+
+# Selenium
+Source: https://docs.browser-use.com/cloud/browser/selenium
+
+
+Browser Use's cloud browsers speak Chrome DevTools Protocol (CDP) over a remote WebSocket. Selenium can't consume that natively: its `debugger_address` option only supports local `host:port` connections, not remote `wss://` URLs.
+
+You have two practical paths.
+
+## Recommended: bridge through a CDP client
+
+If you're migrating Selenium scripts, connect through Playwright's sync API — the page-automation model (navigate, locate, click, read) maps one-to-one, and you get the [hardened stealth Chromium](https://docs.browser-use.com/cloud/browser/stealth) and [residential proxies](https://docs.browser-use.com/cloud/browser/proxies) with no configuration.
+
+```python
+from playwright.sync_api import sync_playwright
+
+WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us"
+
+with sync_playwright() as p:
+ browser = p.chromium.connect_over_cdp(WSS_URL)
+ page = browser.contexts[0].pages[0]
+ page.goto("https://example.com")
+ print(page.title())
+ browser.close()
+# Browser is automatically stopped when the WebSocket disconnects
+```
+
+Common Selenium → Playwright equivalents:
+
+| Selenium | Playwright (sync) |
+|---|---|
+| `driver.get(url)` | `page.goto(url)` |
+| `driver.find_element(By.CSS_SELECTOR, s)` | `page.locator(s)` |
+| `element.click()` | `page.locator(s).click()` |
+| `element.send_keys(text)` | `page.locator(s).fill(text)` |
+| `driver.title` | `page.title()` |
+| `WebDriverWait(...).until(...)` | built-in auto-waiting |
+| `driver.quit()` | `browser.close()` |
+
+### Query parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiKey` | `string` | **Required.** Your Browser Use API key. |
+| `proxyCountryCode` | `string` | Proxy country code (e.g. `us`, `de`, `jp`). 195+ countries. |
+| `profileId` | `string` | Load a saved browser profile (cookies, localStorage). |
+| `timeout` | `int` | Session timeout in minutes. Default: 15. Max: 240 (4 hours). |
+| `browserScreenWidth` | `int` | Browser width in pixels. |
+| `browserScreenHeight` | `int` | Browser height in pixels. |
+
+## Alternative: keep Selenium with a local proxy
+
+If you must keep the Selenium API, run a local WebSocket-to-TCP proxy so Chrome's remote debugging endpoint appears as a local `host:port`, e.g. via [selenium-wire](https://github.com/wkeeling/selenium-wire). This adds a moving part we don't manage — for new code, prefer the CDP bridge above.
+
+ Selenium's `debugger_address` only supports local `host:port` connections. For remote CDP over WebSocket, use [Playwright](https://docs.browser-use.com/cloud/browser/playwright) or [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer) instead.
+
+ Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
+
+## See also
+
+- [Playwright](https://docs.browser-use.com/cloud/browser/playwright) and [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer) connections
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — watch the session or embed it in your app
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies) and [stealth](https://docs.browser-use.com/cloud/browser/stealth) configuration
+
+
+# Cloud browser + open source agent
+Source: https://docs.browser-use.com/cloud/browser/open-source-agent
+
+
+The [open-source library](/open-source/introduction) runs the agent on your machine. By default it also runs the *browser* on your machine, which means no stealth, no residential proxy, and no CAPTCHA solving. This page connects the two: keep your local agent code, point it at a cloud browser.
+
+## Connect by CDP URL
+
+Create a cloud browser, then pass its CDP URL to the library's `Browser`:
+
+```python
+import asyncio
+from browser_use import Agent, Browser, ChatOpenAI
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+async def main():
+ client = AsyncBrowserUse()
+ cloud_browser = await client.browsers.create(proxy_country_code="us")
+
+ try:
+ agent = Agent(
+ task="Find the current price of iPhone 16 on amazon.de",
+ llm=ChatOpenAI(model="gpt-4o"),
+ browser=Browser(cdp_url=cloud_browser.cdp_url),
+ )
+ await agent.run()
+ finally:
+ await client.browsers.stop(cloud_browser.id)
+
+asyncio.run(main())
+```
+
+The agent behaves exactly as it does locally. The browser it drives is a [stealth Chromium](https://docs.browser-use.com/cloud/browser/stealth) with [CAPTCHA solving](https://docs.browser-use.com/cloud/browser/captcha) and a [residential proxy](https://docs.browser-use.com/cloud/browser/proxies), and you can watch it work through the session's `live_url`.
+
+{/* TEAM REVIEW: confirm the `use_cloud=True` shorthand on Browser() — parameter name, minimum library version, and whether it should be the primary example instead of the cdp_url form. */}
+
+## What you get, what you keep
+
+| | Stays yours | Comes from Cloud |
+|---|---|---|
+| Agent loop, prompts, custom tools | ✓ | |
+| LLM choice and API keys | ✓ | |
+| Browser runtime | | ✓ stealth Chromium |
+| Proxy / IP | | ✓ residential, 195+ countries |
+| CAPTCHA handling | | ✓ automatic |
+| Live view and recording | | ✓ per session |
+
+Billing: only the browser session ($0.02/hour plus proxy data). Your LLM tokens go to your own provider.
+
+## Related
+
+- [Create a browser session](https://docs.browser-use.com/cloud/browser/create) — all session parameters
+- [Open source vs Cloud](https://docs.browser-use.com/cloud/open-source-vs-cloud) — the full decision guide
+- [Manage browser sessions](https://docs.browser-use.com/cloud/browser/sessions) — always stop sessions when done
+
+
+# Profiles
+Source: https://docs.browser-use.com/cloud/guides/authentication
+
+
+Create a profile, then pass its `profile_id` to `run()` — the agent opens a browser seeded from that profile and runs your task on it. Cookies and login state saved during the run persist, so the next run with the same profile is already logged in.
```python Python
from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
+
+# 1. Create a profile (stores cookies + login state across runs)
profile = await client.profiles.create(name="user-id-1")
-# or search existing
+# or reuse an existing one:
# profile = (await client.profiles.list(query="user-id-1")).items[0]
-session = await client.sessions.create(profile_id=profile.id)
-result = await client.run("Check browser-use github stars", session_id=session.id)
-print(result.output)
-# Always stop the session to persist profile state
-await client.sessions.stop(session.id)
+# 2. Run the agent — profile_id attaches a browser seeded from the profile
+result = await client.run(
+ "Go to example.com and return the page title",
+ profile_id=profile.id,
+)
+print(result.output) # -> "Example Domain"
+
+# 3. Reuse the same profile later — saved login/cookies carry over
+followup = await client.run("Check my GitHub notifications", profile_id=profile.id)
```
```typescript TypeScript
import { BrowserUse } from "browser-use-sdk/v3";
const client = new BrowserUse();
+
+// 1. Create a profile (stores cookies + login state across runs)
const profile = await client.profiles.create({ name: "user-id-1" });
-// or search existing
+// or reuse an existing one:
// const profile = (await client.profiles.list({ query: "user-id-1" })).items[0];
-const session = await client.sessions.create({ profileId: profile.id });
-const result = await client.run("Check browser-use github stars", {
- sessionId: session.id,
+
+// 2. Run the agent — profileId attaches a browser seeded from the profile
+const result = await client.run("Go to example.com and return the page title", {
+ profileId: profile.id,
});
-console.log(result.output);
+console.log(result.output); // -> "Example Domain"
-// Always stop the session to persist profile state
-await client.sessions.stop(session.id);
+// 3. Reuse the same profile later — saved login/cookies carry over
+const followup = await client.run("Check my GitHub notifications", { profileId: profile.id });
```
+Passing `profile_id` to `run()` provisions the browser and runs the agent in one call — no separate session step. Profile state is saved automatically when the run ends.
+
View your profile IDs at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=profiles).
+## Persist state on a browser you drive (CDP)
+
+Profiles work the same whether the agent drives or you do. Pass `profile_id` to `browsers.create()`, set state over CDP, then **stop the browser to flush cookies and localStorage into the profile**. Reconnect later with the same `profile_id` and the state is there.
+
+```python Python
+from browser_use_sdk.v3 import AsyncBrowserUse
+from playwright.async_api import async_playwright
+
+client = AsyncBrowserUse()
+profile = await client.profiles.create(name="persist-demo")
+
+# Session 1 — write state, then stop to persist
+b1 = await client.browsers.create(profile_id=profile.id)
+async with async_playwright() as p:
+ pw = await p.chromium.connect_over_cdp(b1.cdp_url)
+ page = pw.contexts[0].pages[0]
+ await page.goto("https://en.wikipedia.org")
+ await page.evaluate("localStorage.setItem('demo', 'hello')")
+ await pw.close()
+await client.browsers.stop(b1.id) # flushes state into the profile
+
+# Session 2 — same profile, state is back
+b2 = await client.browsers.create(profile_id=profile.id)
+async with async_playwright() as p:
+ pw = await p.chromium.connect_over_cdp(b2.cdp_url)
+ page = pw.contexts[0].pages[0]
+ await page.goto("https://en.wikipedia.org")
+ value = await page.evaluate("localStorage.getItem('demo')")
+ print(value) # -> hello
+ await pw.close()
+await client.browsers.stop(b2.id)
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v3";
+import { chromium } from "playwright";
+
+const client = new BrowserUse();
+const profile = await client.profiles.create({ name: "persist-demo" });
+
+// Session 1 — write state, then stop to persist
+const b1 = await client.browsers.create({ profileId: profile.id });
+let pw = await chromium.connectOverCDP(b1.cdpUrl);
+let page = pw.contexts()[0].pages()[0];
+await page.goto("https://en.wikipedia.org");
+await page.evaluate(() => localStorage.setItem("demo", "hello"));
+await pw.close();
+await client.browsers.stop(b1.id); // flushes state into the profile
+
+// Session 2 — same profile, state is back
+const b2 = await client.browsers.create({ profileId: profile.id });
+pw = await chromium.connectOverCDP(b2.cdpUrl);
+page = pw.contexts()[0].pages()[0];
+await page.goto("https://en.wikipedia.org");
+console.log(await page.evaluate(() => localStorage.getItem("demo"))); // -> hello
+await pw.close();
+await client.browsers.stop(b2.id);
+```
+
+ Use a site that actually sets cookies/localStorage to verify persistence — `example.com` sets none, so it is a poor test target.
+
## Manage profiles
```python Python
@@ -1437,7 +2445,7 @@ profile = await client.profiles.create(name="work-account")
# List all
response = await client.profiles.list()
for p in response.items:
-print(p.id, p.name)
+ print(p.id, p.name)
# Search by name
response = await client.profiles.list(query="user-id-1")
@@ -1480,10 +2488,14 @@ await client.profiles.delete(profileId);
- **Per-user profiles:** Create one profile per end-user. Query by name to get the profile ID, or store a mapping between your users and their profile IDs in your database.
- Profile state is only saved when the session ends. Always call `sessions.stop()` when you are done — if a session is left open or times out, changes may not be persisted. Every code path that uses a profile must stop the session, including error handlers.
+ Profile state is saved when the run ends — call `sessions.stop()` (agent) or `browsers.stop()` (CDP) when you are done. Both paths persist; a session left open or timed out may not save. Stop in a `finally` so every code path, including error handlers, persists.
+## Further reading
-# Sync local and cloud cookies
+- [How to authenticate AI web agents](https://browser-use.com/posts/web-agent-authentication)
+
+
+# Profiles / Cookie sync
Source: https://docs.browser-use.com/cloud/guides/profile-sync
@@ -1603,8 +2615,8 @@ print(f"Live view: {session.live_url}")
# Agent navigates to login
result = await client.run(
-"Go to example.com/login and enter username user@example.com and password mypassword, then stop before 2FA",
-session_id=session.id,
+ "Go to example.com/login and enter username user@example.com and password mypassword, then stop before 2FA",
+ session_id=session.id,
)
# Human completes 2FA in the live view
@@ -1612,8 +2624,8 @@ input("Complete 2FA in the live view, then press Enter...")
# Agent continues
result = await client.run(
-"You are now logged in. Go to the dashboard and export the monthly report",
-session_id=session.id,
+ "You are now logged in. Go to the dashboard and export the monthly report",
+ session_id=session.id,
)
print(result.output)
await client.sessions.stop(session.id)
@@ -1662,14 +2674,14 @@ from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"""
-1. Go to example.com/signup
-2. Sign up with the agent's email address (use the email available to you)
-3. Check your email inbox for the verification code
-4. Enter the code on the website
-5. Complete the registration
-""",
-agentmail=True, # default, shown for clarity
+ """
+ 1. Go to example.com/signup
+ 2. Sign up with the agent's email address (use the email available to you)
+ 3. Check your email inbox for the verification code
+ 4. Enter the code on the website
+ 5. Complete the registration
+ """,
+ agentmail=True, # default, shown for clarity
)
print(result.output)
```
@@ -1719,16 +2731,16 @@ client = AsyncBrowserUse()
totp_secret = "JBSWY3DPEHPK3PXP"
result = await client.run(
-f"""
-Log into example.com with username user@example.com and password mypassword.
-When prompted for a 2FA code, generate one using pyotp:
+ f"""
+ Log into example.com with username user@example.com and password mypassword.
+ When prompted for a 2FA code, generate one using pyotp:
-import pyotp
-totp = pyotp.TOTP("{totp_secret}")
-code = totp.now()
+ import pyotp
+ totp = pyotp.TOTP("{totp_secret}")
+ code = totp.now()
-Enter the generated code.
-""",
+ Enter the generated code.
+ """,
)
print(result.output)
```
@@ -1772,100 +2784,502 @@ Use **Agent Mail** (enabled by default). For end-client scenarios, have them for
Use **TOTP secret in prompt** — the agent generates codes via pyotp, no human intervention needed.
-# OpenClaw
-Source: https://docs.browser-use.com/cloud/tutorials/integrations/openclaw
+# Webhooks
+Source: https://docs.browser-use.com/cloud/guides/webhooks
-[OpenClaw](https://openclaw.ai) is a self-hosted gateway that connects chat apps like WhatsApp, Telegram, and Discord to AI coding agents. Add Browser Use and those agents get full browser automation — anti-detect profiles, CAPTCHA solving, residential proxies in 195+ countries, and stealth browsing out of the box.
+Set up webhooks at [cloud.browser-use.com/settings?tab=webhooks](https://cloud.browser-use.com/settings?tab=webhooks).
-Two ways to set it up: connect a Browser Use cloud browser to OpenClaw's native browser tool via CDP, or install the Browser Use CLI as a skill.
+## Events
-## Option 1: Cloud Browser via CDP
+| Event | When |
+|-------|------|
+| `agent.task.status_update` | Task status changes (`running`, `idle`, or `stopped`) |
+| `test` | Webhook test ping |
-OpenClaw has a built-in browser tool with its own CLI commands (`openclaw browser`). By default, it controls a local Chromium instance. You can point it at a Browser Use cloud browser instead by configuring a remote CDP profile.
+## Payload
-Browser Use exposes a WebSocket CDP URL. OpenClaw connects to it like any remote browser — no SDK or extra dependencies needed.
+```json
+{
+ "type": "agent.task.status_update",
+ "timestamp": "2025-01-15T10:30:00Z",
+ "payload": {
+ "task_id": "task_abc123",
+ "session_id": "session_xyz",
+ "status": "idle",
+ "metadata": {}
+ }
+}
+```
-### Setup
+## Signature verification
-**1. Get your API key**
+Every webhook request includes two headers:
-Sign up at [cloud.browser-use.com](https://cloud.browser-use.com) and copy your API key from [Settings → API Keys](https://cloud.browser-use.com/settings?tab=api-keys&new=1).
+- `X-Browser-Use-Signature` — HMAC-SHA256 signature of the payload
+- `X-Browser-Use-Timestamp` — Unix timestamp (seconds) when the request was sent
-**2. Add a Browser Use profile**
+The signature is computed over `{timestamp}.{body}`, where `body` is the JSON-serialized payload with keys sorted alphabetically and no extra whitespace. Verify it to ensure the request is authentic and to prevent replay attacks.
-Open `~/.openclaw/openclaw.json` and add a `browser-use` profile:
+```python Python
+import hashlib
+import hmac
+import json
+import time
-```json5
-{
- browser: {
-enabled: true,
-defaultProfile: "browser-use",
-remoteCdpTimeoutMs: 3000,
-remoteCdpHandshakeTimeoutMs: 5000,
-profiles: {
- "browser-use": {
- cdpUrl: "wss://connect.browser-use.com?apiKey=
- {/* Chat column */}
-
+
-
-
- {/* Live browser view — liveUrl available from session creation */}
-
+ {/* Chat column */}
+
);
}
```
@@ -2362,6 +4007,116 @@ useSession();
| `client.sessions.waitForRecording()` | Get MP4 recording URLs |
+# Agent Sign Up for Browser Use
+Source: https://docs.browser-use.com/cloud/agent-signup
+
+
+An AI agent can create its own free Browser Use account without a human opening the dashboard. This is useful when an agent has terminal or HTTP access and needs a Browser Use API key before it can run cloud browser tasks.
+
+The flow is a Browser Use agent challenge: the agent requests a challenge, solves the math problem, verifies the answer, and receives an API key.
+
+## REST flow
+
+### 1. Request a challenge
+
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup \
+ -H "Content-Type: application/json" \
+ -d '{}'
+```
+
+Request body, optional (include a user email/name if available):
+
+```json
+{
+ "email": "user@example.com",
+ "name": "User Name"
+}
+```
+
+Response:
+
+```json
+{
+ "challenge_id": "uuid",
+ "challenge_text": "..."
+}
+```
+
+### 2. Solve the challenge
+
+Read `challenge_text` and solve the math problem. Return the answer as a string with two decimal places, for example `"144.00"`.
+
+### 3. Verify the answer
+
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup/verify \
+ -H "Content-Type: application/json" \
+ -d '{"challenge_id":"uuid","answer":"144.00"}'
+```
+
+Request body:
+
+```json
+{
+ "challenge_id": "uuid",
+ "answer": "144.00"
+}
+```
+
+Response:
+
+```json
+{
+ "api_key": "bu_..."
+}
+```
+
+Use the returned key for Browser Use Cloud API requests.
+
+For example, create a browser session:
+
+```bash
+curl -X POST https://api.browser-use.com/api/v3/browsers \
+ -H "X-Browser-Use-API-Key: bu_..." \
+ -H "Content-Type: application/json" \
+ -d '{}'
+```
+
+See the [Create Browser Session API reference](https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session).
+
+## Claim the account
+
+If a human wants to see the agent-created account in the dashboard later, the agent can create a claim link:
+
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup/claim \
+ -H "X-Browser-Use-API-Key: bu_..."
+```
+
+Response:
+
+```json
+{
+ "claim_url": "https://..."
+}
+```
+
+The claim URL is valid for 1 hour.
+
+## CLI usage
+
+Agents with shell access can use the Browser Use CLI after the REST flow returns an API key:
+
+```bash
+uv tool install browser-use
+export BROWSER_USE_API_KEY=bu_...
+browser-use auth status
+```
+
+Replace `bu_...` with the key returned by the REST flow.
+
+
# Grow Therapy provider search
Source: https://docs.browser-use.com/cloud/tutorials/grow-therapy-compare
@@ -2398,28 +4153,28 @@ const client = new BrowserUse();
```python Python
class Provider(BaseModel):
-name: str
-title: str
-specialties: list[str]
-insurance_plans: list[str]
-rating: float | None = None
-next_available: str | None = None
+ name: str
+ title: str
+ specialties: list[str]
+ insurance_plans: list[str]
+ rating: float | None = None
+ next_available: str | None = None
class ProviderSearch(BaseModel):
-providers: list[Provider]
-total_found: int | None = None
-location: str
-specialty: str
+ providers: list[Provider]
+ total_found: int | None = None
+ location: str
+ specialty: str
```
```typescript TypeScript
const ProviderSearch = z.object({
providers: z.array(z.object({
-name: z.string(),
-title: z.string(),
-specialties: z.array(z.string()),
-insurancePlans: z.array(z.string()),
-rating: z.number().nullable(),
-nextAvailable: z.string().nullable(),
+ name: z.string(),
+ title: z.string(),
+ specialties: z.array(z.string()),
+ insurancePlans: z.array(z.string()),
+ rating: z.number().nullable(),
+ nextAvailable: z.string().nullable(),
})),
totalFound: z.number().nullable(),
location: z.string(),
@@ -2440,19 +4195,19 @@ const workspace = await client.workspaces.create({ name: "grow-therapy-search" }
```python Python
result = await client.run(
-"Go to growtherapy.com and search for therapists in {{New York}} "
-"who specialize in {{anxiety}} and accept insurance. "
-"Return the first 5 provider profiles as JSON.",
-workspace_id=str(workspace.id),
-output_schema=ProviderSearch,
+ "Go to growtherapy.com and search for therapists in {{New York}} "
+ "who specialize in {{anxiety}} and accept insurance. "
+ "Return the first 5 provider profiles as JSON.",
+ workspace_id=str(workspace.id),
+ output_schema=ProviderSearch,
)
for p in result.output.providers:
-print(f"{p.name} ({p.title})")
-print(f" Specialties: {', '.join(p.specialties)}")
-print(f" Rating: {p.rating}")
-print(f" Next available: {p.next_available}")
-print()
+ print(f"{p.name} ({p.title})")
+ print(f" Specialties: {', '.join(p.specialties)}")
+ print(f" Rating: {p.rating}")
+ print(f" Next available: {p.next_available}")
+ print()
```
```typescript TypeScript
const result = await client.run(
@@ -2479,16 +4234,16 @@ locations = ["Los Angeles", "Chicago", "Houston", "Miami"]
specialties = ["depression", "trauma", "ADHD"]
for location in locations:
-for specialty in specialties:
- result = await client.run(
- f"Go to growtherapy.com and search for therapists in {{{{{location}}}}} "
- f"who specialize in {{{{{specialty}}}}} and accept insurance. "
- f"Return the first 5 provider profiles as JSON.",
- workspace_id=str(workspace.id),
- output_schema=ProviderSearch,
- )
- count = len(result.output.providers)
- print(f"{location} / {specialty}: {count} providers found")
+ for specialty in specialties:
+ result = await client.run(
+ f"Go to growtherapy.com and search for therapists in {{{{{location}}}}} "
+ f"who specialize in {{{{{specialty}}}}} and accept insurance. "
+ f"Return the first 5 provider profiles as JSON.",
+ workspace_id=str(workspace.id),
+ output_schema=ProviderSearch,
+ )
+ count = len(result.output.providers)
+ print(f"{location} / {specialty}: {count} providers found")
```
```typescript TypeScript
const locations = ["Los Angeles", "Chicago", "Houston", "Miami"];
@@ -2496,13 +4251,13 @@ const specialties = ["depression", "trauma", "ADHD"];
for (const location of locations) {
for (const specialty of specialties) {
-const result = await client.run(
- `Go to growtherapy.com and search for therapists in {{${location}}} ` +
- `who specialize in {{${specialty}}} and accept insurance. ` +
- `Return the first 5 provider profiles as JSON.`,
- { workspaceId: workspace.id, schema: ProviderSearch },
-);
-console.log(`${location} / ${specialty}: ${result.output.providers.length} providers`);
+ const result = await client.run(
+ `Go to growtherapy.com and search for therapists in {{${location}}} ` +
+ `who specialize in {{${specialty}}} and accept insurance. ` +
+ `Return the first 5 provider profiles as JSON.`,
+ { workspaceId: workspace.id, schema: ProviderSearch },
+ );
+ console.log(`${location} / ${specialty}: ${result.output.providers.length} providers`);
}
}
```
@@ -2587,7 +4342,6 @@ Source: https://docs.browser-use.com/cloud/legacy/agent
| Model | API String | Cost per Step |
| ----- | ---------- | ------------- |
| Browser Use 2.0 (default) | `browser-use-2.0` | \$0.006 |
-| Browser Use LLM | `browser-use-llm` | \$0.002 |
| O3 | `o3` | \$0.03 |
| Gemini Flash Latest | `gemini-flash-latest` | \$0.0075 |
| Gemini Flash Lite Latest | `gemini-flash-lite-latest` | \$0.005 |
@@ -2621,15 +4375,15 @@ client = AsyncBrowserUse()
session = await client.sessions.create()
upload = await client.files.session_url(
-session.id,
-file_name="input.pdf",
-content_type="application/pdf",
-size_bytes=1024,
+ session.id,
+ file_name="input.pdf",
+ content_type="application/pdf",
+ size_bytes=1024,
)
with open("input.pdf", "rb") as f:
-async with httpx.AsyncClient() as http:
- await http.post(upload.url, content=f.read(), headers={"Content-Type": "application/pdf"})
+ async with httpx.AsyncClient() as http:
+ await http.post(upload.url, content=f.read(), headers={"Content-Type": "application/pdf"})
result = await client.run("Summarize the uploaded PDF", session_id=session.id)
```
@@ -2662,8 +4416,8 @@ const result = await client.run("Summarize the uploaded PDF", { sessionId: sessi
```python Python
result = await client.tasks.get(task_id)
for file in result.output_files:
-output = await client.files.task_output(task_id, file.id)
-print(output.download_url) # download URL
+ output = await client.files.task_output(task_id, file.id)
+ print(output.download_url) # download URL
```
```typescript TypeScript
const result = await client.tasks.get(taskId);
@@ -2685,8 +4439,8 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
run = client.run("Find the most upvoted post on Reddit r/technology today")
async for step in run:
-print(f"Step {step.number}: {step.next_goal}")
-print(f" URL: {step.url}")
+ print(f"Step {step.number}: {step.next_goal}")
+ print(f" URL: {step.url}")
print(run.result.output) # final result after iteration
```
@@ -2767,8 +4521,8 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
skill = await client.skills.create(
-goal="Extract the top X posts from HackerNews. For each post return: title, URL, score, author, comment count, and rank. X is an input parameter.",
-agent_prompt="Go to https://news.ycombinator.com, click on the first post to load its content, go back to the list, and scroll down to trigger loading of additional posts.",
+ goal="Extract the top X posts from HackerNews. For each post return: title, URL, score, author, comment count, and rank. X is an input parameter.",
+ agent_prompt="Go to https://news.ycombinator.com, click on the first post to load its content, go back to the list, and scroll down to trigger loading of additional posts.",
)
print(skill.id)
```
@@ -2789,8 +4543,8 @@ Skill creation takes ~30 seconds. You can also create skills visually from the [
```python Python
result = await client.skills.execute(
-skill.id,
-parameters={"X": 10},
+ skill.id,
+ parameters={"X": 10},
)
print(result)
```
@@ -2862,9 +4616,9 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"Log into my Jira account and create a new ticket",
-op_vault_id="your-vault-id",
-allowed_domains=["*.atlassian.net"],
+ "Log into my Jira account and create a new ticket",
+ op_vault_id="your-vault-id",
+ allowed_domains=["*.atlassian.net"],
)
print(result.output)
```
@@ -2875,8 +4629,8 @@ const client = new BrowserUse();
const result = await client.run(
"Log into my Jira account and create a new ticket",
{
-opVaultId: "your-vault-id",
-allowedDomains: ["*.atlassian.net"],
+ opVaultId: "your-vault-id",
+ allowedDomains: ["*.atlassian.net"],
},
);
console.log(result.output);
@@ -2886,17 +4640,17 @@ For SSO/OAuth redirects, include all required domains:
```python Python
result = await client.run(
-"Log into Jira and create a ticket for the Q4 release",
-op_vault_id="your-vault-id",
-allowed_domains=["*.atlassian.net", "*.okta.com"],
+ "Log into Jira and create a ticket for the Q4 release",
+ op_vault_id="your-vault-id",
+ allowed_domains=["*.atlassian.net", "*.okta.com"],
)
```
```typescript TypeScript
const result = await client.run(
"Log into Jira and create a ticket for the Q4 release",
{
-opVaultId: "your-vault-id",
-allowedDomains: ["*.atlassian.net", "*.okta.com"],
+ opVaultId: "your-vault-id",
+ allowedDomains: ["*.atlassian.net", "*.okta.com"],
},
);
```
@@ -2924,9 +4678,9 @@ from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run(
-"Log into GitHub and star the browser-use/browser-use repo",
-secrets={"github.com": "username:password123"},
-allowed_domains=["github.com"],
+ "Log into GitHub and star the browser-use/browser-use repo",
+ secrets={"github.com": "username:password123"},
+ allowed_domains=["github.com"],
)
```
```typescript TypeScript
@@ -2936,8 +4690,8 @@ const client = new BrowserUse();
const result = await client.run(
"Log into GitHub and star the browser-use/browser-use repo",
{
-secrets: { "github.com": "username:password123" },
-allowedDomains: ["github.com"],
+ secrets: { "github.com": "username:password123" },
+ allowedDomains: ["github.com"],
},
);
```
@@ -2948,28 +4702,85 @@ For SSO/OAuth redirects, include all domains in the auth flow:
```python Python
result = await client.run(
-"Log into the company portal and download the Q4 report",
-secrets={
- "portal.example.com": "user@company.com:password123",
- "okta.com": "user@company.com:password123",
-},
-allowed_domains=["portal.example.com", "*.okta.com"],
+ "Log into the company portal and download the Q4 report",
+ secrets={
+ "portal.example.com": "user@company.com:password123",
+ "okta.com": "user@company.com:password123",
+ },
+ allowed_domains=["portal.example.com", "*.okta.com"],
)
```
```typescript TypeScript
const result = await client.run(
"Log into the company portal and download the Q4 report",
{
-secrets: {
- "portal.example.com": "user@company.com:password123",
- "okta.com": "user@company.com:password123",
-},
-allowedDomains: ["portal.example.com", "*.okta.com"],
+ secrets: {
+ "portal.example.com": "user@company.com:password123",
+ "okta.com": "user@company.com:password123",
+ },
+ allowedDomains: ["portal.example.com", "*.okta.com"],
},
);
```
+# API Reference
+Source: https://docs.browser-use.com/cloud/api-v4-overview
+
+
+## Authentication
+
+All requests require an API key in the `X-Browser-Use-API-Key` header:
+
+```
+X-Browser-Use-API-Key: bu_your_key_here
+```
+
+Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=api-keys&new=1). Keys start with `bu_`.
+
+## Base URL
+
+```
+https://api.browser-use.com/api/v4
+```
+
+## The core loop
+
+Create a run, poll its status until terminal, then fetch the full result. `status` is a cheap indexed lookup — poll it, not the full run.
+
+```bash Create a run
+curl -X POST https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: bu_your_key_here" \
+ -H "Content-Type: application/json" \
+ -d '{"task": "Find the top 3 trending repos on GitHub today"}'
+```
+
+```bash Poll status until completed | failed | cancelled (replace RUN_ID)
+curl https://api.browser-use.com/api/v4/runs/RUN_ID/status \
+ -H "X-Browser-Use-API-Key: bu_your_key_here"
+```
+
+```bash Fetch the full run once it's terminal
+curl https://api.browser-use.com/api/v4/runs/RUN_ID \
+ -H "X-Browser-Use-API-Key: bu_your_key_here"
+```
+
+## Sessions and follow-ups
+
+A run belongs to a session (a conversation). Send a follow-up message to a session's queue — it runs as the next turn, or immediately with `interrupt: true`:
+
+```bash Queue a follow-up (replace SESSION_ID)
+curl -X POST https://api.browser-use.com/api/v4/sessions/SESSION_ID/queue \
+ -H "X-Browser-Use-API-Key: bu_your_key_here" \
+ -H "Content-Type: application/json" \
+ -d '{"text": "Now open the top result", "interrupt": false}'
+```
+
+## SDKs
+
+The [Cloud SDK](https://docs.browser-use.com/cloud/sdk) wraps this loop — `runs.create()` then `runs.waitForCompletion()` / `runs.wait_for_completion()` — for TypeScript and Python.
+
+
# API Reference
Source: https://docs.browser-use.com/cloud/api-reference
@@ -2990,6 +4801,16 @@ Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/sett
https://api.browser-use.com/api/v3
```
+## OpenAPI spec
+
+The full API surface is published as a machine-readable OpenAPI 3.1 spec — use it to generate typed clients or validate payloads:
+
+```
+https://docs.browser-use.com/openapi.json
+```
+
+Also at [/cloud/openapi/v3.json](https://docs.browser-use.com/cloud/openapi/v3.json). Legacy v2 spec: [/cloud/openapi/v2.json](https://docs.browser-use.com/cloud/openapi/v2.json).
+
## Quick example
```bash Create a session
@@ -3036,6 +4857,8 @@ export BROWSER_USE_API_KEY=your_key
Base URL: `https://api.browser-use.com/api/v2`
+OpenAPI spec: [/cloud/openapi/v2.json](https://docs.browser-use.com/cloud/openapi/v2.json) — legacy; new projects should use [v3](https://docs.browser-use.com/openapi.json).
+
---
Prefer the SDK? See the [Agent (v2) docs](https://docs.browser-use.com/cloud/legacy/agent).
@@ -3047,65 +4870,3 @@ pip install browser-use-sdk
npm install browser-use-sdk
```
-
-## Browser Use Agent Challenge to Get a Free Account
-
-AI agents can create a free Browser Use account autonomously via a challenge-response flow at `https://api.browser-use.com`.
-
-Do this to get an API key (no human required):
-1. `POST https://api.browser-use.com/cloud/signup` — request a challenge.
-
-Request body, optional (include a user email/name if available):
-```json
-{
- "email": "user@example.com",
- "name": "User Name"
-}
-```
-
-Response:
-```json
-{
- "challenge_id": "uuid",
- "challenge_text": "..."
-}
-```
-
-2. Solve the math problem in `challenge_text` — answer as a string with 2 decimal places, e.g. `"144.00"`
-
-3. `POST https://api.browser-use.com/cloud/signup/verify` with `challenge_id` + `answer`.
-
-Request body:
-```json
-{
- "challenge_id": "uuid",
- "answer": "144.00"
-}
-```
-
-Response:
-```json
-{
- "api_key": "bu_..."
-}
-```
-
-4. Use `X-Browser-Use-API-Key: bu_...` on Browser Use Cloud API requests. For example, create a browser session (docs: https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session):
-
-```bash
-curl -X POST https://api.browser-use.com/api/v3/browsers \
- -H "X-Browser-Use-API-Key: bu_..." \
- -H "Content-Type: application/json" \
- -d '{}'
-```
-
-To let a human claim the account later: `POST https://api.browser-use.com/cloud/signup/claim` with `X-Browser-Use-API-Key: bu_...`.
-
-Response:
-```json
-{
- "claim_url": "https://..."
-}
-```
-
-The claim URL is valid for 1 hour.
diff --git a/docs/llms.txt b/docs/llms.txt
index 8b1c30c10..163bdb756 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -5,7 +5,7 @@
- Dashboard: https://cloud.browser-use.com
- Create API key: https://cloud.browser-use.com/settings?tab=api-keys&new=1
- Docs: https://docs.browser-use.com
-- OpenAPI spec (v3): https://docs.browser-use.com/cloud/openapi/v3.json
+- OpenAPI spec (v3): https://docs.browser-use.com/openapi.json (also at /cloud/openapi/v3.json; legacy v2: /cloud/openapi/v2.json)
- Chat UI example: https://docs.browser-use.com/cloud/tutorials/chat-ui — Full end-to-end example with live browser, streaming, auth. Best starting point to build a prototype.
- Open-source repo: https://github.com/browser-use/browser-use — The open-source Python library. Note: the open-source API is different from the Cloud SDK. If you want the easiest path to production with managed infrastructure, use the Cloud SDK below.
@@ -22,12 +22,16 @@ export BROWSER_USE_API_KEY=bu_your_key_here
## Get Started
+- [Introduction](https://docs.browser-use.com/cloud/introduction): AI browser agents that run on stealth cloud browsers — one API key, driven as much or as little as you want.
+- [Open source vs Cloud](https://docs.browser-use.com/cloud/open-source-vs-cloud): The library and the cloud are different products that combine. Here's which one you want.
- [Quick start](https://docs.browser-use.com/cloud/quickstart): State-of-the-art AI browser automation with stealth browsers, CAPTCHA solving, residential proxies, and managed infrastructure.
-- [Agent Sign Up for Browser Use](https://docs.browser-use.com/cloud/agent-signup): How an AI agent can complete the Browser Use agent challenge to get a free account and API key.
+- [Pricing & free tier](https://docs.browser-use.com/cloud/pricing): Browser Use Cloud plans, the free tier (no card required), and every usage-based rate.
- [Prompt for Vibecoders](https://docs.browser-use.com/cloud/vibecoding): Complete Cloud SDK reference for AI coding agents.
## Agent
+- [Overview](https://docs.browser-use.com/cloud/agent/overview): The hosted agent takes a task in plain language and drives a stealth browser until it's done.
- [Introduction](https://docs.browser-use.com/cloud/agent/quickstart): Easiest way to automate the web. Tell this agent in natural language what it should do, and it can interact with the web like a human.
+- [Sessions](https://docs.browser-use.com/cloud/agent/sessions): One cloud browser plus the tasks an agent runs inside it.
- [Models](https://docs.browser-use.com/cloud/agent/models): Choose the right model for your task.
- [Structured output](https://docs.browser-use.com/cloud/agent/structured-output): Get validated, typed data back from agent tasks.
- [Follow-up tasks](https://docs.browser-use.com/cloud/agent/follow-up-tasks): Run multiple tasks in the same browser session.
@@ -37,27 +41,44 @@ export BROWSER_USE_API_KEY=bu_your_key_here
- [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop): Let a human interact with the live browser while the agent is running. Useful for approvals, payments, complex auth flows, or reviewing agent work before continuing.
## Browser
-- [Introduction Stealth](https://docs.browser-use.com/cloud/browser/stealth): Best stealth on the planet. We fork Chromium to give agents access to all websites.
+- [Overview](https://docs.browser-use.com/cloud/browser/overview): Remote stealth browsers you control over CDP. What they are and when to use one.
+- [Create a browser session](https://docs.browser-use.com/cloud/browser/create): Every way to start a cloud browser: SDK, REST, or a single WebSocket URL, with all parameters and the response schema.
+- [Manage browser sessions](https://docs.browser-use.com/cloud/browser/sessions): Session lifecycle: states, timeouts, stopping, disconnect behavior, and what you're billed for.
+- [Stealth](https://docs.browser-use.com/cloud/browser/stealth): Best stealth on the planet. We fork Chromium to give agents access to all websites.
+- [CAPTCHA Solving](https://docs.browser-use.com/cloud/browser/captcha): Browser Use remote browsers solve CAPTCHAs automatically, on by default, on every plan.
- [Proxies](https://docs.browser-use.com/cloud/browser/proxies): Residential proxies in 195+ countries. On by default.
+- [Screenshots](https://docs.browser-use.com/cloud/browser/screenshots): Take viewport and full-page screenshots from a cloud browser session, and control where they're saved.
- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview): Watch the agent's browser in real time. Embed it in your app.
-- [Playwright, Puppeteer, Selenium](https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium): Connect your automation framework to Browser Use's stealth infrastructure via CDP.
+- [Cloud browser + open source agent](https://docs.browser-use.com/cloud/browser/open-source-agent): Run the open-source Browser Use agent on a cloud stealth browser. Your code, our infrastructure.
+
+## Automation frameworks
+- [Playwright](https://docs.browser-use.com/cloud/browser/playwright): Connect Playwright to a remote stealth browser over CDP — Python and TypeScript.
+- [Puppeteer](https://docs.browser-use.com/cloud/browser/puppeteer): Connect Puppeteer to a remote stealth browser with browserWSEndpoint.
+- [Selenium](https://docs.browser-use.com/cloud/browser/selenium): Run Selenium-style automation on Browser Use's stealth browsers — and why to bridge through CDP.
## Authentication
- [Profiles](https://docs.browser-use.com/cloud/guides/authentication): Persistent browser state — cookies, localStorage, saved passwords. Login once, reuse across sessions.
-- [Sync local and cloud cookies](https://docs.browser-use.com/cloud/guides/profile-sync): Sync your local browser cookies to the cloud — instantly authenticate without managing credentials.
+- [Profiles / Cookie sync](https://docs.browser-use.com/cloud/guides/profile-sync): Profiles carry cookies and login state across sessions — sync them from your local browser or reuse them in the cloud.
- [2FA](https://docs.browser-use.com/cloud/guides/2fa): Best practices for handling two-factor authentication in automated browser sessions.
## More
- [FAQ](https://docs.browser-use.com/cloud/faq): Common questions and solutions.
+## Platform features
+- [Webhooks](https://docs.browser-use.com/cloud/guides/webhooks): Receive real-time notifications when tasks complete. Configure webhook endpoints for async task monitoring.
+- [x402 (pay-per-request)](https://docs.browser-use.com/cloud/guides/x402): Pay for Browser Use Cloud with crypto (USDC on Base). ~30 seconds from wallet to first request.
+
## Integrations
-- [OpenClaw](https://docs.browser-use.com/cloud/tutorials/integrations/openclaw): Give OpenClaw agents browser automation with Browser Use — via CDP or the CLI skill.
- [MCP Server](https://docs.browser-use.com/cloud/guides/mcp-server): Run browser automation tasks from your AI coding assistant. Connect to Claude, Cursor, Windsurf, or any MCP client.
-- [Webhooks](https://docs.browser-use.com/cloud/guides/webhooks): Receive real-time notifications when tasks complete. Configure webhook endpoints for async task monitoring.
+- [Claude Code](https://docs.browser-use.com/cloud/tutorials/integrations/claude-code): Give Claude Code cloud browser automation with Browser Use.
+- [Claude Managed Agents](https://docs.browser-use.com/cloud/tutorials/integrations/claude-managed-agents): Give Anthropic's Claude Managed Agents a stealth cloud browser via the Browser Use CLI.
+- [OpenClaw](https://docs.browser-use.com/cloud/tutorials/integrations/openclaw): Give OpenClaw agents browser automation with Browser Use — via CDP or the CLI skill.
+- [Hermes Agent](https://docs.browser-use.com/cloud/tutorials/integrations/hermes-agent): Give Hermes Agent cloud browser automation with Browser Use.
- [n8n](https://docs.browser-use.com/cloud/tutorials/integrations/n8n): Use Browser Use as an HTTP node in n8n workflows.
## Tutorials
- [Chat UI](https://docs.browser-use.com/cloud/tutorials/chat-ui): Full end-to-end example. Build a chat UI with live browser preview, follow-up tasks, recording, and streaming messages.
+- [Agent Sign Up for Browser Use](https://docs.browser-use.com/cloud/agent-signup): How the Browser Use agent challenge lets an AI agent create a free account and API key.
- [Grow Therapy provider search](https://docs.browser-use.com/cloud/tutorials/grow-therapy-compare): Search Grow Therapy for therapists by location, insurance, and specialty — with cached reruns.
## Legacy (v2)
@@ -67,70 +88,12 @@ export BROWSER_USE_API_KEY=bu_your_key_here
- [1Password & 2FA](https://docs.browser-use.com/cloud/guides/1password): Auto-fill passwords and TOTP codes from 1Password during agent tasks.
- [Secrets](https://docs.browser-use.com/cloud/guides/secrets): Pass domain-scoped credentials to the agent securely.
+## API v4
+- [API Reference](https://docs.browser-use.com/cloud/api-v4-overview): Authenticate and start using the Browser Use API v4 — the current REST API for long-horizon agents.
+
## API v3
- [API Reference](https://docs.browser-use.com/cloud/api-reference): Authenticate and start using the Browser Use REST API.
## API v2
- [API key](https://docs.browser-use.com/cloud/api-v2-overview): Set your API key to access the Browser Use v2 REST API.
-## Browser Use Agent Challenge to Get a Free Account
-
-AI agents can create a free Browser Use account autonomously via a challenge-response flow at `https://api.browser-use.com`.
-
-Do this to get an API key (no human required):
-1. `POST https://api.browser-use.com/cloud/signup` — request a challenge.
-
-Request body, optional (include a user email/name if available):
-```json
-{
- "email": "user@example.com",
- "name": "User Name"
-}
-```
-
-Response:
-```json
-{
- "challenge_id": "uuid",
- "challenge_text": "..."
-}
-```
-
-2. Solve the math problem in `challenge_text` — answer as a string with 2 decimal places, e.g. `"144.00"`
-
-3. `POST https://api.browser-use.com/cloud/signup/verify` with `challenge_id` + `answer`.
-
-Request body:
-```json
-{
- "challenge_id": "uuid",
- "answer": "144.00"
-}
-```
-
-Response:
-```json
-{
- "api_key": "bu_..."
-}
-```
-
-4. Use `X-Browser-Use-API-Key: bu_...` on Browser Use Cloud API requests. For example, create a browser session (docs: https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session):
-
-```bash
-curl -X POST https://api.browser-use.com/api/v3/browsers \
- -H "X-Browser-Use-API-Key: bu_..." \
- -H "Content-Type: application/json" \
- -d '{}'
-```
-
-To let a human claim the account later: `POST https://api.browser-use.com/cloud/signup/claim` with `X-Browser-Use-API-Key: bu_...`.
-
-Response:
-```json
-{
- "claim_url": "https://..."
-}
-```
-
-The claim URL is valid for 1 hour.
diff --git a/docs/open-source/llms-full.txt b/docs/open-source/llms-full.txt
index 267626a73..8e93d0fc9 100644
--- a/docs/open-source/llms-full.txt
+++ b/docs/open-source/llms-full.txt
@@ -192,6 +192,8 @@ Browser Use natively supports 15+ LLM providers. Most providers accept any model
`ChatBrowserUse()` is our optimized in-house model, matching the accuracy of top models while completing tasks **3-5x** faster. [See our blog post→](https://browser-use.com/posts/speed-matters)
+ Read the [bu-2-0 model card](/open-source/bu-2-0-model-card) for details on intended use, inputs and outputs, tools, benchmarks, judge setup, and limitations.
+
```python
from browser_use import Agent, ChatBrowserUse
@@ -738,13 +740,13 @@ Any provider with an OpenAI-compatible endpoint works via `ChatOpenAI` with a cu
Source: https://docs.browser-use.com/open-source/browser-use-cli
-The Browser Use CLI (`browser-use`) is the command-line interface for the Browser Use platform. It uses [Browser Harness](https://github.com/browser-use/browser-harness) to allow for:
+The Browser Use CLI (`browser-use`) gives coding agents a direct browser-control surface backed by [Browser Harness](https://github.com/browser-use/browser-harness):
- **Direct browser control** — agents run Python to do actions in the browser.
- **Three browser modes** — you can use with local Chrome or Chromium with your existing tabs, cookies, extensions, and logins; Browser Use cloud browsers; or any browser reachable through a CDP endpoint.
- **Agent-ready setup** — install the skill into Claude Code, Codex, and other coding agents so they know when and how to call the CLI.
-To try the hosted agent directly, use [Browser Use Cloud](https://cloud.browser-use.com?utm_source=docs&utm_medium=browser-use-cli&utm_campaign=v4), or install the skill.
+Try out Browser Use CLI with an agent in [Browser Use Cloud](https://cloud.browser-use.com?utm_source=docs&utm_medium=browser-use-cli&utm_campaign=v4), or install the skill to try it yourself locally.
## Install the CLI
@@ -868,9 +870,7 @@ Give this employee admin permission in Azure.
Research the top Hacker News stories and summarize the points.
```
-
+
+
+ {/* Live browser view — liveUrl available from session creation */}
+