+
-// Same task again — cached
-result = await client.run(
- "Get the current Bitcoin price from coinmarketcap.com @{{}}",
- { workspaceId: workspace.id },
-);
-```
+Set `browser_settings` / `browserSettings` when you create a V4 run to choose
+another country:
-### Multiple parameters
+ The current TypeScript SDK type requires `proxyCountryCode` whenever
+ `browserSettings` is present. Use `"us"` to keep the default, or `null` to
+ disable the managed proxy.
```python Python
-result = await client.run(
-"Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{Germany,France,Japan}}",
-workspace_id=str(workspace.id),
-)
+from browser_use_sdk.v4 import BrowserUse
-# Different countries — cached
-result2 = await client.run(
-"Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{US,UK,Brazil}}",
-workspace_id=str(workspace.id),
+client = BrowserUse()
+run = client.runs.create(
+ "Get the iPhone 16 price on amazon.de",
+ browser_settings={"proxyCountryCode": "de"},
)
```
```typescript TypeScript
-let result = await client.run(
- "Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{Germany,France,Japan}}",
- { workspaceId: workspace.id },
-);
+import { BrowserUse } from "browser-use-sdk/v4";
-// Different countries — cached
-result = await client.run(
- "Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{US,UK,Brazil}}",
- { workspaceId: workspace.id },
-);
+const client = new BrowserUse();
+const run = await client.runs.create({
+ task: "Get the iPhone 16 price on amazon.de",
+ model: "grok-4.5",
+ browserSettings: { proxyCountryCode: "de" },
+});
+```
+```bash curl
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Get the iPhone 16 price on amazon.de",
+ "browserSettings":{"proxyCountryCode":"de"}}'
```
-### Force enable / disable
+## Disable proxies
-```python Python
-# Force-enable without brackets
-result = await client.run(
-"Get the top stories from Hacker News",
-workspace_id=str(workspace.id),
-cache_script=True,
-)
+Pass `null` for QA or internal sites that do not need a residential proxy:
-# Force-disable even with brackets
-result = await client.run(
-"Explain what @{{templates}} means in Jinja",
-workspace_id=str(workspace.id),
-cache_script=False,
+```python Python
+run = client.runs.create(
+ "Test my staging site",
+ browser_settings={"proxyCountryCode": None},
)
```
```typescript TypeScript
-// Force-enable without brackets
-let result = await client.run(
- "Get the top stories from Hacker News",
- { workspaceId: workspace.id, cacheScript: true },
-);
-
-// Force-disable even with brackets
-result = await client.run(
- "Explain what @{{templates}} means in Jinja",
- { workspaceId: workspace.id, cacheScript: false },
-);
+const run = await client.runs.create({
+ task: "Test my staging site",
+ model: "grok-4.5",
+ browserSettings: { proxyCountryCode: null },
+});
```
-## Inspecting cached scripts
+## Custom proxy
-You can download and inspect the scripts the agent created:
+Custom HTTP and SOCKS5 proxies are available on paid plans:
```python Python
-files = await client.workspaces.files(workspace.id, prefix="scripts/")
-for f in files.files:
-print(f"{f.path} ({f.size} bytes)")
-
-# Download a script to inspect it
-await client.workspaces.download(workspace.id, "scripts/a7f3b2c1.py", to="./my_script.py")
+run = client.runs.create(
+ "Check the account dashboard",
+ browser_settings={
+ "customProxy": {
+ "host": "proxy.example.com",
+ "port": 8080,
+ "username": "user",
+ "password": "pass",
+ "ignoreCertErrors": False,
+ }
+ },
+)
```
```typescript TypeScript
-const files = await client.workspaces.files(workspace.id, { prefix: "scripts/" });
-for (const f of files.files) {
- console.log(`${f.path} (${f.size} bytes)`);
-}
+const run = await client.runs.create({
+ task: "Check the account dashboard",
+ model: "grok-4.5",
+ browserSettings: {
+ proxyCountryCode: "us",
+ customProxy: {
+ host: "proxy.example.com",
+ port: 8080,
+ username: "user",
+ password: "pass",
+ ignoreCertErrors: false,
+ },
+ },
+});
```
-## Auto-healing
-
-Cached scripts can break when a website changes its layout, adds new elements, or alters its structure. Auto-healing detects these failures and automatically regenerates the script.
+A custom proxy overrides `proxyCountryCode` and must be passed again when a
+follow-up provisions a new browser. See the [Create run
+reference](https://docs.browser-use.com/cloud/api-v4/runs/create-run) for the complete settings object.
-### How it works
-
-When a cached script runs, the system validates its output:
+# Live preview & recording
+Source: https://docs.browser-use.com/cloud/browser/live-preview
-1. **Fast checks** (no LLM) — detects empty results, error fields in JSON, or exception keywords in output.
-2. **LLM judge** — if fast checks pass, a lightweight model validates whether the output looks correct for the original task.
-3. **Heal** — if validation fails, the full agent re-runs the task and saves an updated script.
-Auto-healing is **limited to 1 attempt per run** to prevent runaway costs. If the healed script also fails, the output is returned as-is.
+The `browser.ready` event contains the live browser URL:
-### Cost impact
+```python Python
+from browser_use_sdk.v4 import BrowserUse
-| Scenario | LLM cost |
-|----------|----------|
-| Cached script succeeds | **$0** |
-| Cached script fails, auto-heals | ~$0.05–1.00 (one full agent run) |
-| Healed script also fails | Same as above (returns best-effort output) |
+client = BrowserUse()
+run = client.runs.create("Find the top Hacker News story")
+run = client.runs.wait_for_completion(run.id)
-Auto-healing is enabled by default for all cached scripts. No configuration needed.
+events = client.runs.events(run.id, limit=100)
+ready = next(
+ event for event in events.events
+ if event.type == "browser.ready"
+)
+print(ready.data["live_view_url"])
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v4";
-## Cost comparison
+const client = new BrowserUse();
+const run = await client.runs.create({
+ task: "Find the top Hacker News story",
+ model: "grok-4.5",
+});
+await client.runs.waitForCompletion(run.id);
-| | LLM cost | Browser + proxy | Time |
-|---|---|---|---|
-| First call (agent) | ~$0.05–1.00 | Yes | ~30–120s |
-| Cached calls | **$0** | Yes | ~3–10s |
+const events = await client.runs.events(run.id, {
+ limit: 100,
+});
+const ready = events.events.find(
+ (event) => event.type === "browser.ready",
+);
+console.log(ready?.data.live_view_url);
+```
-The browser and proxy still run for cached calls (the script may need them), so there is a small infrastructure cost per execution. LLM cost drops to zero.
+Poll [run events](https://docs.browser-use.com/cloud/agent/observability) if you need the URL as soon as
+the browser starts.
+## Embed the live browser
-# Human in the loop
-Source: https://docs.browser-use.com/cloud/agent/human-in-the-loop
+```html
+
+```
+The URL is hosted on `live.browser-use.com`. Add that origin to your
+Content Security Policy's `frame-src` directive when needed. Treat the URL as
+a credential: anyone with it can interact with the active browser.
-## Use cases
-- Human enters payment info or approves a transaction, agent handles the rest
-- Human navigates a complex auth flow, then hands back to agent
-- Human reviews what the agent did before the agent continues
+## Recording
- Sessions time out after 15 minutes of inactivity. The maximum session duration is 4 hours. If the human needs more time, send a lightweight follow-up task (e.g. "wait") to reset the inactivity timer.
+Enable recording when the run creates its browser:
-## Flow
+```python Python
+run = client.runs.create(
+ "Test the checkout flow",
+ browser_settings={"record": True},
+)
+```
+```typescript TypeScript
+const run = await client.runs.create({
+ task: "Test the checkout flow",
+ model: "grok-4.5",
+ browserSettings: { proxyCountryCode: "us", record: true },
+});
+```
+```bash curl
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Test checkout","browserSettings":{"record":true}}'
+```
-1. Create a session — it stays alive automatically when you pass `session_id` to `run()`
-2. Run an agent task
-3. Human interacts with the live browser
-4. Send a new follow-up task
+The MP4 becomes available in the Dashboard after the browser stops. API runs
+default to recording off, and Zero Data Retention projects never record.
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+# Playwright, Puppeteer, Selenium
+Source: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium
-client = AsyncBrowserUse()
-# 1. Create a session
-session = await client.sessions.create()
-print(f"Live view: {session.live_url}")
+Every browser 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.
-# 2. Agent does the first part
-result = await client.run(
-"Go to amazon.com and search for noise cancelling headphones",
-session_id=session.id,
-)
-print(result.output)
+ This page is for direct browser control. To give an AI agent a goal instead,
+ [create an API V4 run](https://docs.browser-use.com/cloud/agent/quickstart).
-# 3. Human opens live_url and picks a product
-input("Press Enter after you've selected a product in the live view...")
+## 1. Create a browser
-# 4. Agent continues where the human left off
-result = await client.run(
-"Get the details of the selected product — name, price, and rating",
-session_id=session.id,
-)
-print(result.output)
+```bash
+session=$(curl -sS https://api.browser-use.com/api/v4/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"proxyCountryCode":"us"}')
-# Clean up
-await client.sessions.stop(session.id)
+export BROWSER_SESSION_ID=$(echo "$session" | jq -r .id)
+export BROWSER_USE_CDP_URL=$(echo "$session" | jq -r .cdpUrl)
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import * as readline from "readline";
-const client = new BrowserUse();
+## 2. Connect over CDP
-// 1. Create a session
-const session = await client.sessions.create();
-console.log(`Live view: ${session.liveUrl}`);
+### Playwright
-// 2. Agent does the first part
-const searchResult = await client.run(
- "Go to amazon.com and search for noise cancelling headphones",
- { sessionId: session.id },
-);
-console.log(searchResult.output);
+```python Python
+import os
+from playwright.sync_api import sync_playwright
-// 3. Human opens liveUrl and picks a product
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-await new Promise((resolve) =>
- rl.question("Press Enter after you've selected a product in the live view...", resolve),
-);
-rl.close();
+with sync_playwright() as p:
+ browser = p.chromium.connect_over_cdp(os.environ["BROWSER_USE_CDP_URL"])
+ page = browser.contexts[0].pages[0]
+ page.goto("https://example.com")
+ print(page.title())
+```
+```typescript TypeScript
+import { chromium } from "playwright";
-// 4. Agent continues where the human left off
-const result = await client.run(
- "Get the details of the selected product — name, price, and rating",
- { sessionId: session.id },
+const browser = await chromium.connectOverCDP(
+ process.env.BROWSER_USE_CDP_URL!,
);
-console.log(result.output);
-
-// Clean up
-await client.sessions.stop(session.id);
+const page = browser.contexts()[0].pages()[0];
+await page.goto("https://example.com");
+console.log(await page.title());
```
+### Puppeteer
+```typescript
+import puppeteer from "puppeteer-core";
-# Introduction Stealth
-Source: https://docs.browser-use.com/cloud/browser/stealth
+const browser = await puppeteer.connect({
+ browserWSEndpoint: process.env.BROWSER_USE_CDP_URL!,
+});
+const [page] = await browser.pages();
+await page.goto("https://example.com");
+console.log(await page.title());
+```
+### Selenium
-See [how we perform in the hardest stealth benchmark](https://browser-use.com/posts/stealth-benchmark).
+Selenium's `debugger_address` only supports local `host:port` connections.
+Use Playwright or Puppeteer for remote CDP over WebSocket.
-## What's included
+## 3. Stop the browser
-Every cloud browser session runs in a hardened Chromium fork with stealth enabled by default — no configuration needed.
+```bash
+curl -X PATCH \
+ "https://api.browser-use.com/api/v4/browsers/$BROWSER_SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action":"stop"}'
+```
-- **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.
+ `browser.close()` and disconnecting CDP do not stop the managed browser.
+ Call `PATCH /api/v4/browsers/{id}` with `{"action":"stop"}`.
-## Residential proxies
+See [Create browser session](https://docs.browser-use.com/cloud/api-v4/browsers/create-browser-session) and
+[Update browser session](https://docs.browser-use.com/cloud/api-v4/browsers/update-browser-session) for
+every browser setting and response field.
-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.
+# Profiles
+Source: https://docs.browser-use.com/cloud/guides/authentication
-# Proxies
-Source: https://docs.browser-use.com/cloud/browser/proxies
+A profile persists cookies, local storage, and login state across browsers.
+Log in once, save the profile, then reuse it to start future browsers already
+logged in.
+
+
-A US residential proxy is active by default on every browser. To route through a different country, set `proxy_country_code`. See the [API reference](https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session) for all supported country codes.
+Create or select one under [Dashboard → Profiles](https://cloud.browser-use.com/settings?tab=profiles),
+then pass its ID in V4 browser settings:
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-browser = await client.browsers.create(proxy_country_code="de")
-print(browser.cdp_url) # ws://...
-print(browser.live_url) # debug view
+from browser_use_sdk.v4 import BrowserUse
-# With an agent:
-# result = await client.run("Get the price of iPhone 16 on amazon.de", proxy_country_code="de")
+client = BrowserUse()
+run = client.runs.create(
+ "Open my account dashboard and summarize it",
+ browser_settings={"profileId": "YOUR_PROFILE_ID"},
+)
+result = client.runs.wait_for_completion(run.id)
+print(result.result)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
-const browser = await client.browsers.create({ proxyCountryCode: "de" });
-console.log(browser.cdpUrl);
-console.log(browser.liveUrl);
-
-// With an agent:
-// const result = await client.run("Get the price of iPhone 16 on amazon.de", { proxyCountryCode: "de" });
+const run = await client.runs.create({
+ task: "Open my account dashboard and summarize it",
+ model: "grok-4.5",
+ browserSettings: {
+ profileId: "YOUR_PROFILE_ID",
+ proxyCountryCode: "us",
+ },
+});
+const result = await client.runs.waitForCompletion(run.id);
+console.log(result.result);
+```
+```bash curl
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Summarize my account dashboard",
+ "browserSettings":{"profileId":"YOUR_PROFILE_ID"}}'
```
-## Disable proxies
+Use one profile per end user. Follow-ups in the same [session](https://docs.browser-use.com/cloud/agent/sessions)
+reuse the live browser; later sessions can load the same profile again.
-If your use case does not need proxies, for example QA testing.
+For the fastest setup, [sync an existing local login](https://docs.browser-use.com/cloud/guides/profile-sync).
-```python Python
-browser = await client.browsers.create(proxy_country_code=None)
+# Sync local and cloud cookies
+Source: https://docs.browser-use.com/cloud/guides/profile-sync
-# With an agent:
-# result = await client.run("Go to http://localhost:3000", proxy_country_code=None)
-```
-```typescript TypeScript
-const browser = await client.browsers.create({ proxyCountryCode: null });
-// With an agent:
-// const result = await client.run("Go to http://localhost:3000", { proxyCountryCode: null });
-```
+Run the profile sync helper:
-## Custom proxy
+```bash
+export BROWSER_USE_API_KEY=your_key
+curl -fsSL https://browser-use.com/profile.sh | sh
+```
-Bring your own proxy server (HTTP or SOCKS5).
+Choose the accounts to sync, then use the returned profile ID:
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+from browser_use_sdk.v4 import BrowserUse
-client = AsyncBrowserUse()
-browser = await client.browsers.create(
-custom_proxy={
- "host": "proxy.example.com",
- "port": 8080,
- "username": "user",
- "password": "pass",
-},
+client = BrowserUse()
+run = client.runs.create(
+ "Check my LinkedIn messages",
+ browser_settings={"profileId": "YOUR_PROFILE_ID"},
)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
-const browser = await client.browsers.create({
- customProxy: {
-host: "proxy.example.com",
-port: 8080,
-username: "user",
-password: "pass",
+const run = await client.runs.create({
+ task: "Check my LinkedIn messages",
+ model: "grok-4.5",
+ browserSettings: {
+ profileId: "YOUR_PROFILE_ID",
+ proxyCountryCode: "us",
},
});
```
+The profile supplies cookies and local storage without putting credentials in
+the prompt. Re-sync when the site's login expires.
-# Live preview & recording
-Source: https://docs.browser-use.com/cloud/browser/live-preview
+# 2FA
+Source: https://docs.browser-use.com/cloud/guides/2fa
- Want a ready-made UI? See the [Chat UI tutorial](https://docs.browser-use.com/cloud/tutorials/chat-ui).
+The most reliable options are a saved profile or a human checkpoint.
-`liveUrl` is returned on session creation.
+## Reuse a logged-in profile
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+[Sync your local login](https://docs.browser-use.com/cloud/guides/profile-sync), then load that profile in
+the run:
-client = AsyncBrowserUse()
-session = await client.sessions.create(task="Check how many GitHub stars browser-use has")
-print(session.live_url)
+```python Python
+run = client.runs.create(
+ "Download my latest invoice",
+ browser_settings={"profileId": "YOUR_PROFILE_ID"},
+)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const session = await client.sessions.create({
- task: "Check how many GitHub stars browser-use has",
+const run = await client.runs.create({
+ task: "Download my latest invoice",
+ model: "grok-4.5",
+ browserSettings: {
+ profileId: "YOUR_PROFILE_ID",
+ proxyCountryCode: "us",
+ },
});
-console.log(session.liveUrl);
```
-`liveUrl` is also returned when creating a standalone browser session:
+This avoids another 2FA challenge while the site's cookies remain valid.
+
+## Let a human take over
+
+Ask the first run to stop at the 2FA screen, get its `live_view_url` from the
+[`browser.ready` event](https://docs.browser-use.com/cloud/agent/human-in-the-loop), and have the user enter
+the code. Then continue with the same session:
```python Python
-browser = await client.browsers.create()
-print(browser.live_url)
+first = client.runs.create(
+ "Open the login page and stop at the 2FA prompt",
+)
+client.runs.wait_for_completion(first.id)
+
+next_run = client.runs.create(
+ "Continue after login and download the invoice",
+ session_id=first.session_id,
+)
```
```typescript TypeScript
-const browser = await client.browsers.create();
-console.log(browser.liveUrl);
+const first = await client.runs.create({
+ task: "Open the login page and stop at the 2FA prompt",
+ model: "grok-4.5",
+});
+await client.runs.waitForCompletion(first.id);
+
+const nextRun = await client.runs.create({
+ task: "Continue after login and download the invoice",
+ model: "grok-4.5",
+ sessionId: first.sessionId,
+});
```
-## Embed live browser into your app
+See [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) for retrieving and
+embedding the live browser URL. Never put passwords or TOTP secrets directly
+in a prompt.
-Useful for human interaction or to see live what's happening.
+# Claude Code
+Source: https://docs.browser-use.com/cloud/tutorials/integrations/claude-code
-```html
-
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) is Anthropic's agentic coding tool that runs in the terminal. Add Browser Use and it gets full cloud browser automation — anti-detect profiles, CAPTCHA solving, residential proxies in 195+ countries, persistent profiles, and stealth browsing.
+
+## Setup
+
+**1. Install the CLI**
+
+```bash
+uv tool install browser-use
```
-The live URL is hosted on `live.browser-use.com`. If your app sets a Content Security Policy, add it to your `frame-src` directive:
+**2. Verify the installation**
+```bash
+browser-use doctor
```
-Content-Security-Policy: frame-src 'self' https://live.browser-use.com;
+
+**3. Register the skill**
+
+Register the Browser Use skill with the installed CLI:
+
+```bash
+browser-use skill install
```
-For responsive sizing, use CSS instead of fixed dimensions:
+**4. Authenticate for cloud browsers**
-```html
-
+Sign up at [cloud.browser-use.com](https://cloud.browser-use.com), then authenticate:
+
+```bash
+browser-use auth login
```
-## Customize
+Or let Claude Code provision a free API key itself — see [Agent Self-Registration](#agent-self-registration) below.
-Append query parameters to the `liveUrl`:
+**5. Use it**
-| Parameter | Values | Description |
-|-----------|--------|-------------|
-| `theme` | `light`, `dark` (default) | Light or dark mode |
-| `ui` | `false` | Hide the browser chrome (URL bar, tabs) |
+Claude Code uses its bash tool to run CLI commands directly:
```
-https://live.browser-use.com?wss=...&theme=light
-https://live.browser-use.com?wss=...&ui=false
+> Use browser-use to open github.com/trending and summarize the top repos
```
-## Recording
+For the complete CLI reference and Python execution examples, see the [Browser Use CLI docs](https://docs.browser-use.com/open-source/browser-use-cli).
- `waitForRecording` / `wait_for_recording` requires the **v3 SDK** (`from browser_use_sdk.v3 import AsyncBrowserUse` / `import { BrowserUse } from "browser-use-sdk/v3"`).
+## Agent Self-Registration
-Enable recording to get an MP4 video of the browser session. Only available when the agent actually opens a browser — tasks answered without browsing produce no recording. If you run multiple tasks in the same session (with `keep_alive`), you may get multiple recordings.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-result = await client.run(
-"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
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const result = await client.run("Check how many GitHub stars browser-use has", {
- enableRecording: true,
-});
-
-// Waits up to 15s for recording to be ready. Returns [] if no browser was opened.
-const urls = await client.sessions.waitForRecording(result.id);
-for (const url of urls) {
- console.log(url); // presigned MP4 download URL
-}
-```
-
-For standalone browser sessions, pass `enable_recording` when creating the browser and retrieve the URL after stopping it:
-
-```python Python
-browser = await client.browsers.create(enable_recording=True)
-# ... use the browser via CDP ...
-stopped = await client.browsers.stop(browser.id)
-print(stopped.recording_url) # presigned MP4 download URL
-```
-```typescript TypeScript
-const browser = await client.browsers.create({ enableRecording: true });
-// ... use the browser via CDP ...
-const stopped = await client.browsers.stop(browser.id);
-console.log(stopped.recordingUrl); // presigned MP4 download URL
-```
-
- Recording URLs are presigned and **expire after 1 hour**. Download or serve the recording promptly. If you need to access it later, save the MP4 to your own storage.
-
-## Related
-
-- [Live messages](https://docs.browser-use.com/cloud/agent/streaming) — stream the agent's messages alongside the live browser view
-- [Follow-up tasks](https://docs.browser-use.com/cloud/agent/follow-up-tasks) — chain tasks in one session while watching live
-
-
-
-# Playwright, Puppeteer, Selenium
-Source: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium
-
-
-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.
-
-## 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 is automatically stopped when the WebSocket disconnects
-```
-```typescript TypeScript
-import { chromium } from "playwright";
-
-const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";
-
-const browser = await chromium.connectOverCDP(WSS_URL);
-const page = browser.contexts()[0].pages()[0];
-await page.goto("https://example.com");
-console.log(await page.title());
-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
-
-| 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, get a `cdp_url`, and connect with Playwright or Puppeteer.
-
-### Playwright
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-from playwright.async_api import async_playwright
-
-client = AsyncBrowserUse()
-browser = await client.browsers.create()
-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()
-
-await client.browsers.stop(browser.id)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import { chromium } from "playwright";
-
-const client = new BrowserUse();
-const browser = await client.browsers.create();
-console.log(browser.cdpUrl); // https://uuid.cdpN.browser-use.com
-console.log(browser.liveUrl); // https://live.browser-use.com?wss=...
-
-const pwBrowser = await chromium.connectOverCDP(browser.cdpUrl);
-const page = pwBrowser.contexts()[0].pages()[0];
-await page.goto("https://example.com");
-console.log(await page.title());
-await pwBrowser.close();
-
-await client.browsers.stop(browser.id);
-```
-
-### Puppeteer
-
-```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 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();
-
-await client.browsers.stop(browser.id);
-```
-
- Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
-
-
-# Profiles
-Source: https://docs.browser-use.com/cloud/guides/authentication
-
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-profile = await client.profiles.create(name="user-id-1")
-# or search existing
-# 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)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const profile = await client.profiles.create({ name: "user-id-1" });
-// or search existing
-// 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,
-});
-console.log(result.output);
-
-// Always stop the session to persist profile state
-await client.sessions.stop(session.id);
-```
-
-View your profile IDs at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=profiles).
-
-## Manage profiles
-
-```python Python
-# Create
-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)
-
-# Search by name
-response = await client.profiles.list(query="user-id-1")
-profile = response.items[0] # first match
-
-# Get one by ID
-profile = await client.profiles.get(profile_id)
-
-# Update
-await client.profiles.update(profile_id, name="renamed")
-
-# Delete
-await client.profiles.delete(profile_id)
-```
-```typescript TypeScript
-// Create
-const profile = await client.profiles.create({ name: "work-account" });
-
-// List all
-const response = await client.profiles.list();
-for (const p of response.items) {
- console.log(p.id, p.name);
-}
-
-// Search by name
-const results = await client.profiles.list({ query: "user-id-1" });
-const found = results.items[0]; // first match
-
-// Get one by ID
-const fetched = await client.profiles.get(profileId);
-
-// Update
-await client.profiles.update(profileId, { name: "renamed" });
-
-// Delete
-await client.profiles.delete(profileId);
-```
-
-## Usage patterns
-
-- **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.
-
-
-# Sync local and cloud cookies
-Source: https://docs.browser-use.com/cloud/guides/profile-sync
+Claude Code can provision its own Browser Use API key autonomously — no human interaction needed. The free tier includes unlimited browser hours, free proxies in 195+ countries, persistent browser profiles, CAPTCHA solving, and stealth browsing at zero cost.
+Install the Browser Use CLI and skill:
```bash
-export BROWSER_USE_API_KEY=your_key && curl -fsSL https://browser-use.com/profile.sh | sh
-```
-
-This opens a browser where you select which accounts to sync. After syncing, you receive a `profile_id` to use in your tasks.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-session = await client.sessions.create(profile_id="your_synced_profile_id")
-result = await client.run("Check my LinkedIn messages", session_id=session.id)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const session = await client.sessions.create({ profileId: "your_synced_profile_id" });
-const result = await client.run("Check my LinkedIn messages", {
- sessionId: session.id,
-});
-```
-
-
-# 2FA
-Source: https://docs.browser-use.com/cloud/guides/2fa
-
-
-Sites with 2FA block automated logins. Here are four approaches — pick the one that fits your setup.
-
-| Approach | Best for | Complexity |
-|---|---|---|
-| [Profiles (login once)](#1-profiles--login-once-reuse-cookies) | Sites with long-lived cookies | Lowest |
-| [Human in the loop](#2-human-in-the-loop) | One-off tasks, complex auth flows | Low |
-| [Agent Mail](#3-agent-mail) | Email-based 2FA, end-client automation | Medium |
-| [TOTP secret in prompt](#4-totp-secret-in-prompt) | Authenticator app 2FA (Google Authenticator, Authy) | Medium |
-
----
-
-## 1. Profiles — login once, reuse cookies
-
-Login manually once (or let the agent do it), then save the browser state as a profile. Future sessions reuse the cookies — no 2FA prompt as long as the cookies are valid.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-
-# Create a profile and a session
-profile = await client.profiles.create(name="my-account")
-session = await client.sessions.create(profile_id=profile.id)
-print(f"Live view: {session.live_url}")
-
-# Option A: human logs in via live view
-input("Log in and complete 2FA in the live view, then press Enter...")
-
-# Option B: let the agent log in
-# await client.run("Log in to example.com with user@example.com / password123", session_id=session.id)
-
-# Stop the session — this saves cookies to the profile
-await client.sessions.stop(session.id)
-
-# Next time: reuse the profile, no 2FA needed
-session = await client.sessions.create(profile_id=profile.id)
-result = await client.run("Go to example.com/dashboard and get my balance", session_id=session.id)
-print(result.output)
-await client.sessions.stop(session.id)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import * as readline from "readline";
-
-const client = new BrowserUse();
-
-// Create a profile and a session
-const profile = await client.profiles.create({ name: "my-account" });
-const session = await client.sessions.create({ profileId: profile.id });
-console.log(`Live view: ${session.liveUrl}`);
-
-// Option A: human logs in via live view
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-await new Promise((resolve) => rl.question("Log in and complete 2FA in the live view, then press Enter...", resolve));
-rl.close();
-
-// Option B: let the agent log in
-// await client.run("Log in to example.com with user@example.com / password123", { sessionId: session.id });
-
-// Stop the session — this saves cookies to the profile
-await client.sessions.stop(session.id);
-
-// Next time: reuse the profile, no 2FA needed
-const newSession = await client.sessions.create({ profileId: profile.id });
-const result = await client.run("Go to example.com/dashboard and get my balance", { sessionId: newSession.id });
-console.log(result.output);
-await client.sessions.stop(newSession.id);
-```
-
- Cookies expire. Some sites stay logged in for months, others expire daily. If your sessions start hitting login pages again, re-authenticate and save the profile.
-
- Always call `sessions.stop()` after you're done — profile state is only saved when the session ends cleanly.
-
----
-
-## 2. Human in the loop
-
-Let the agent navigate to the login page, then a human takes over to complete 2FA via the live browser view. The agent continues after.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-session = await client.sessions.create()
-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,
-)
-
-# Human completes 2FA in the live view
-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,
-)
-print(result.output)
-await client.sessions.stop(session.id)
+uv tool install browser-use
+browser-use skill install
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import * as readline from "readline";
-const client = new BrowserUse();
-const session = await client.sessions.create();
-console.log(`Live view: ${session.liveUrl}`);
+Claude Code can follow the [REST flow](https://docs.browser-use.com/cloud/agent-signup#rest-flow) to request and verify a challenge, then put the returned key in its shell environment:
-// Agent navigates to login
-await client.run(
- "Go to example.com/login and enter username user@example.com and password mypassword, then stop before 2FA",
- { sessionId: session.id },
-);
-
-// Human completes 2FA in the live view
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-await new Promise((resolve) => rl.question("Complete 2FA in the live view, then press Enter...", resolve));
-rl.close();
-
-// Agent continues
-const result = await client.run(
- "You are now logged in. Go to the dashboard and export the monthly report",
- { sessionId: session.id },
-);
-console.log(result.output);
-await client.sessions.stop(session.id);
+```bash
+export BROWSER_USE_API_KEY=bu_...
+browser-use auth status
```
-See [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) for more patterns.
+### Claim the account (optional)
----
+If the human wants to see the account in the dashboard later, use the [claim endpoint](https://docs.browser-use.com/cloud/agent-signup#claim-the-account). The returned claim URL is valid for 1 hour.
-## 3. Agent Mail
+# Claude Managed Agents
+Source: https://docs.browser-use.com/cloud/tutorials/integrations/claude-managed-agents
-When 2FA sends a code via email, the agent can read it automatically using Agent Mail — a built-in email inbox for each session.
-Agent Mail is **enabled by default** (`agentmail=True`). Each session gets a unique email address (`session.agentmail_email`). The agent can send and receive emails during the task.
+[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents) run on Anthropic's hosted platform. Install the `browser-use` CLI in the agent's environment and it can drive a stealth cloud browser — with proxies, CAPTCHA solving, live view, and recording. Your API key stays in a credential vault; the model never sees it.
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
+The sandbox can't run a local browser, so the agent starts a named Browser Use Cloud browser and drives it with `browser-use <<'PY'` Python snippets.
-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
-)
-print(result.output)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+## 1. Create an environment
-const client = new BrowserUse();
+Pre-install the CLI so it's ready at session start (no runtime install).
-const 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
-);
-console.log(result.output);
+```yaml
+name: browser-env
+config:
+ type: cloud
+ packages:
+ pip:
+ - browser-use
+ networking:
+ type: limited
+ allowed_hosts: ["*.browser-use.com"]
+ allow_package_managers: true
```
-### For end-client automation
-
-If you're automating on behalf of your users and they need to receive 2FA codes:
-
-1. **Email forwarding:** Have your client set up an email forwarding rule — forward all emails from the service (e.g., `noreply@bank.com`) to a dedicated inbox (a Gmail address or an Agent Mail address).
-2. **Give the agent access:** The agent reads the forwarded 2FA code from that inbox during the task.
-
-This way, your client's real email stays private — the agent only sees the forwarded verification emails.
+## 2. Create a credential vault
-### Connect external email via Composio
+Store your key as an environment variable so the CLI reads it and the model never does. Get one at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=api-keys&new=1).
-You can also give the agent access to an existing Gmail account using [Composio](https://composio.dev) in the Browser Use dashboard. Once connected, the agent can read emails directly from that account to retrieve 2FA codes.
+| Field | Value |
+| ----- | --------------------- |
+| Type | Environment variable |
+| Name | `BROWSER_USE_API_KEY` |
+| Value | `bu_...` |
----
-
-## 4. TOTP secret in prompt
-
-If the site uses an authenticator app (Google Authenticator, Authy, etc.), you can pass the TOTP secret to the agent. Our agent can execute Python code, so it uses the `pyotp` library to generate fresh 6-digit codes on the fly.
-
-When you set up 2FA on a site, instead of only scanning the QR code, also copy the **secret key** (usually shown as "manual entry" or "can't scan the QR code?"). This is a long base32 string like `JBSWY3DPEHPK3PXP`.
+## 3. Create the agent
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
+Tell it to use the CLI in cloud mode.
-# The TOTP secret from your authenticator setup — NOT the 6-digit code
-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:
-
-import pyotp
-totp = pyotp.TOTP("{totp_secret}")
-code = totp.now()
-
-Enter the generated code.
-""",
-)
-print(result.output)
+```yaml
+name: browser agent
+model:
+ id: claude-opus-4-8
+description: Drives a stealth cloud browser with the Browser Use CLI.
+system: |
+ You are a browser agent. Use the `browser-use` CLI to complete web tasks.
+ Never launch a local browser in this sandbox. Start a named cloud browser:
+ browser-use <<'PY'
+ start_remote_daemon("managed")
+ PY
+ Then run browser work through the same name:
+ BU_NAME=managed browser-use <<'PY'
+ new_tab("https://example.com")
+ print(page_info())
+ PY
+ Your BROWSER_USE_API_KEY is in the environment; never print it.
+tools:
+ - type: agent_toolset_20260401 # shell access so the agent can run the CLI
+ default_config:
+ enabled: true
+ permission_policy:
+ type: always_allow
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-// The TOTP secret from your authenticator setup — NOT the 6-digit code
-const totpSecret = "JBSWY3DPEHPK3PXP";
+## 4. Start a session and send a task
-const result = await client.run(
- `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("${totpSecret}")
- code = totp.now()
+The Console only observes; kick the agent off with a `user.message` event.
- Enter the generated code.`,
-);
-console.log(result.output);
+```bash
+curl -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "anthropic-version: 2023-06-01" \
+ -H "anthropic-beta: managed-agents-2026-04-01" \
+ -H "content-type: application/json" \
+ -d '{"events":[{"type":"user.message","content":[{"type":"text",
+ "text":"Get the top 5 Hacker News stories with their links."}]}]}'
```
-This works because the Browser Use agent can execute Python code as part of its task. The agent runs `pyotp.TOTP(secret).now()` to generate a time-based 6-digit code, then types it into the 2FA field.
-
-### Where to find TOTP secrets
-
-- **1Password**: Edit item → One-Time Password → Show secret
-- **Google Authenticator**: During setup, click "Can't scan it?" to see the key
-- **Authy**: Export via desktop app settings
-- **Most sites**: Look for "manual entry" or "setup key" during 2FA enrollment
-
----
-
-## Which approach should I use?
+## 5. Watch it run
-Start with **Profiles** — log in once, reuse cookies. If cookies expire frequently, add **TOTP secret in prompt** for fully automated re-login.
-Use **Profiles** with one profile per user. For initial login, use **Human in the loop** — your user logs in once via the live view, then the agent reuses the session. For email 2FA, set up **Agent Mail** with email forwarding from your user.
-Use **Agent Mail** (enabled by default). For end-client scenarios, have them forward 2FA emails to a dedicated inbox.
-Use **TOTP secret in prompt** — the agent generates codes via pyotp, no human intervention needed.
+The agent starts a named cloud browser, runs Python helper snippets through `browser-use`, then returns the result. The session shows up in [cloud.browser-use.com](https://cloud.browser-use.com) → **Remote Browsers** with a **Live View** and an **mp4 recording**.
+ Always use a cloud browser — the Managed Agents sandbox has no GUI, so a local
+ browser won't start. Cloud mode also gives you stealth, residential proxies,
+ live view, and recording.
# OpenClaw
Source: https://docs.browser-use.com/cloud/tutorials/integrations/openclaw
@@ -1798,733 +1293,314 @@ Open `~/.openclaw/openclaw.json` and add a `browser-use` profile:
```json5
{
- browser: {
-enabled: true,
-defaultProfile: "browser-use",
-remoteCdpTimeoutMs: 3000,
-remoteCdpHandshakeTimeoutMs: 5000,
-profiles: {
- "browser-use": {
- cdpUrl: "wss://connect.browser-use.com?apiKey=
- {/* Chat column */}
-
- );
-}
+```bash
+export BROWSER_USE_API_KEY=bu_...
+browser-use auth status
```
----
+### Claim the account (optional)
-## Summary
+If the human wants to see the account in the dashboard later, use the [claim endpoint](https://docs.browser-use.com/cloud/agent-signup#claim-the-account). The returned claim URL is valid for 1 hour.
-| Method | Purpose |
-|--------|---------|
-| `client.sessions.create()` | Create a session (returns `liveUrl` immediately) |
-| `client.run()` | Send a task and stream messages with `for await` |
-| `client.sessions.stop()` | Stop the current task |
-| `client.sessions.waitForRecording()` | Get MP4 recording URLs |
+# Agent Sign Up for Browser Use
+Source: https://docs.browser-use.com/cloud/agent-signup
-# Grow Therapy provider search
-Source: https://docs.browser-use.com/cloud/tutorials/grow-therapy-compare
+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.
-This tutorial builds a provider search tool for [Grow Therapy](https://www.growtherapy.com) — a therapy marketplace that handles insurance credentialing for providers. We combine [structured output](https://docs.browser-use.com/cloud/agent/structured-output) with [deterministic rerun](https://docs.browser-use.com/cloud/agent/cache-script) to build a fast, repeatable search pipeline.
+## REST flow
-## What you'll build
+### 1. Request a challenge
-A script that:
-1. Searches Grow Therapy's provider directory with filters (location, insurance, specialty)
-2. Extracts therapist profiles with ratings and availability
-3. Caches the search so you can sweep across geographies or specialties instantly
+```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):
-## Setup
+```json
+{
+ "email": "user@example.com",
+ "name": "User Name"
+}
+```
-```python Python
-import asyncio
-import json
-from pydantic import BaseModel
-from browser_use_sdk.v3 import AsyncBrowserUse
+Response:
-client = AsyncBrowserUse()
+```json
+{
+ "challenge_id": "uuid",
+ "challenge_text": "..."
+}
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import { z } from "zod";
-const client = new BrowserUse();
-```
+### 2. Solve the challenge
-## 1. Define the output schema
+Read `challenge_text` and solve the math problem. Return the answer as a string with two decimal places, for example `"144.00"`.
-```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
-
-class ProviderSearch(BaseModel):
-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(),
- })),
- totalFound: z.number().nullable(),
- location: z.string(),
- specialty: z.string(),
-});
+### 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"}'
```
-## 2. Create a workspace
+Request body:
-```python Python
-workspace = await client.workspaces.create(name="grow-therapy-search")
+```json
+{
+ "challenge_id": "uuid",
+ "answer": "144.00"
+}
```
-```typescript TypeScript
-const workspace = await client.workspaces.create({ name: "grow-therapy-search" });
+
+Response:
+
+```json
+{
+ "api_key": "bu_..."
+}
```
-## 3. Search for providers
+Use the returned key for Browser Use Cloud API requests.
-```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,
-)
+For example, create an API V4 run:
-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()
+```bash
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: bu_..." \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Find the top Hacker News story"}'
```
-```typescript TypeScript
-const 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.",
- { workspaceId: workspace.id, schema: ProviderSearch },
-);
-for (const p of result.output.providers) {
- console.log(`${p.name} (${p.title})`);
- console.log(` Specialties: ${p.specialties.join(", ")}`);
- console.log(` Rating: ${p.rating}`);
- console.log(` Next available: ${p.nextAvailable}`);
-}
-```
+See the [API V4 quick start](https://docs.browser-use.com/cloud/agent/quickstart).
-## 4. Sweep across locations and specialties
+## Claim the account
-After the first run caches the search flow, sweep across different parameters at $0 LLM cost:
+If a human wants to see the agent-created account in the dashboard later, the agent can create a claim link:
-```python Python
-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")
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup/claim \
+ -H "X-Browser-Use-API-Key: bu_..."
```
-```typescript TypeScript
-const locations = ["Los Angeles", "Chicago", "Houston", "Miami"];
-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`);
- }
+Response:
+
+```json
+{
+ "claim_url": "https://..."
}
```
----
-
-## Summary
-
-| Step | What happens | Cost |
-|------|-------------|------|
-| First search | Agent navigates Grow Therapy, caches the flow | ~$0.10 |
-| 12 cached sweeps (4 cities x 3 specialties) | Script reruns with new params | **$0 LLM each** |
-| Site layout change | [Auto-healing](https://docs.browser-use.com/cloud/agent/cache-script#auto-healing) regenerates the script | ~$0.10 |
+The claim URL is valid for 1 hour.
-Therapy platforms have dynamic UIs that can change frequently. [Auto-healing](https://docs.browser-use.com/cloud/agent/cache-script#auto-healing) ensures your cached scripts stay working without manual maintenance.
+## CLI usage
-## Next steps
+Agents with shell access can use the Browser Use CLI after the REST flow returns an API key:
-- [Structured output](https://docs.browser-use.com/cloud/agent/structured-output) — Learn more about extracting typed data with Pydantic and Zod schemas.
-- [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) — Let a human review or interact with the browser mid-task, useful for auth flows or approving results before continuing.
-- [Deterministic rerun](https://docs.browser-use.com/cloud/agent/cache-script) — Deep dive into how caching and auto-healing work.
+```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.
# FAQ
Source: https://docs.browser-use.com/cloud/faq
@@ -2532,19 +1608,30 @@ Source: https://docs.browser-use.com/cloud/faq
## Which model should I use?
-- **Claude Opus 4.6** (`claude-opus-4.6`) — most capable. Use for the hardest tasks that need maximum accuracy.
-- **Claude Sonnet 4.6** (`claude-sonnet-4.6`, default) — best balance of capability and cost. Use for complex multi-step workflows.
-- **GPT-5.4 mini** (`gpt-5.4-mini`) — fast and efficient. Good for simple, well-defined tasks.
+- **Claude Opus 5** (`claude-opus-5`) — maximum intelligence for difficult, long-horizon work.
+- **GPT-5.6** (`gpt-5.6`) — fast on complex tasks.
+- **Gemini 3.5 Flash** (`gemini-3.5-flash`) — fast for simpler tasks.
+- **MiniMax M3** (`minimax-m3`, default) — cheapest for simple and high-volume tasks.
+
+See [Models](https://docs.browser-use.com/cloud/agent/models) for the complete V4 picker and pricing.
## How do I get the live browser URL?
-`live_url` is returned on session creation. Embed it in an iframe or open it in a browser.
+The V4 run's `browser.ready` event contains `live_view_url`. Embed it in an iframe or open it in a browser.
```python
-session = await client.sessions.create(task="Go to example.com")
-print(session.live_url)
+from browser_use_sdk.v4 import BrowserUse
+
+client = BrowserUse()
+created = client.runs.create("Go to example.com")
+client.runs.wait_for_completion(created.id)
+events = client.runs.events(created.id, limit=100)
+ready = next(event for event in events.events if event.type == "browser.ready")
+print(ready.data["live_view_url"])
```
+Poll events until `browser.ready` appears if you need the URL while the run is still active. See [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) for a complete flow.
+
## Getting blocked by a website
Stealth and proxies are active by default. If you're still getting blocked:
@@ -2558,25 +1645,21 @@ If it still doesn't work, contact support inside the [Cloud Dashboard](https://c
The SDK auto-retries 429 responses with exponential backoff. If persistent, you may need more concurrent sessions — contact support.
-## v2 vs v3 — which should I use?
-
-**v3 is the recommendation for everything.** It's a premium agent (not available in open source) that is significantly more capable than v2:
+## V2 or V4 — which should I use?
-- **Much better at complex tasks** and multi-step workflows
-- **Much better at large data extraction**
-- **File system** with persistent memory across tasks
-- **Task scheduling** with 1,000+ integrations (Gmail, Slack, and more)
+Use **V4** for difficult tasks where accuracy matters. It supports:
-v2 is the closest to the open-source experience — pure browser automation, nothing else. If the open source already works great for your use case, v2 is the natural fit. For everything else, use v3.
+- Run-focused API with a cheap status polling endpoint
+- Conversation sessions with follow-ups
+- Persistent workspaces and turn-scoped file attachments
+- Incremental events for custom UIs and monitoring
+- Per-run cost totals, cost caps, and optional judgement
-```python
-# v3 (recommended)
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-# v2 (simple browser-only tasks)
-from browser_use_sdk.v2 import AsyncBrowserUse
-```
+Use **V2** when tasks are simple and your priority is very low cost and
+predictable speed. Its accuracy is substantially lower.
+See Browser Use at #1 on the
+[Odysseys benchmark](https://odysseysbench.com/leaderboard).
# Agent (v2)
Source: https://docs.browser-use.com/cloud/legacy/agent
@@ -2587,7 +1670,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 +1703,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 +1744,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 +1767,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
```
@@ -2727,7 +1809,6 @@ console.log(run.result?.output); // final result after iteration
| `op_vault_id` | `str` | 1Password vault ID for auto-fill credentials and 2FA. |
| `metadata` | `dict[str, str]` | Custom metadata attached to the task. |
-
# Public share links (v2)
Source: https://docs.browser-use.com/cloud/legacy/public-share
@@ -2743,7 +1824,6 @@ const share = await client.sessions.createShare(session.id);
console.log(share.shareUrl);
```
-
# Skills
Source: https://docs.browser-use.com/cloud/legacy/skills
@@ -2767,8 +1847,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 +1869,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)
```
@@ -2831,7 +1911,6 @@ const result = await client.marketplace.execute(skillId, { parameters: { ... } }
See [Pricing](https://browser-use.com/pricing) for skill costs.
-
# 1Password & 2FA
Source: https://docs.browser-use.com/cloud/guides/1password
@@ -2862,9 +1941,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 +1954,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 +1965,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"],
},
);
```
@@ -2912,7 +1991,6 @@ When the agent encounters a login form:
The agent never sees your actual credentials. The actual username, password, and 2FA codes are filled in programmatically — keeping your secrets hidden from the AI model.
-
# Secrets
Source: https://docs.browser-use.com/cloud/guides/secrets
@@ -2924,9 +2002,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 +2014,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,30 +2026,29 @@ 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-reference
+Source: https://docs.browser-use.com/cloud/api-v4-overview
## Authentication
@@ -2987,42 +2064,44 @@ Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/sett
## Base URL
```
-https://api.browser-use.com/api/v3
+https://api.browser-use.com/api/v4
```
-## Quick example
+## The core loop
-```bash Create a session
-curl -X POST https://api.browser-use.com/api/v3/sessions \
+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 Get session result (replace SESSION_ID)
-curl https://api.browser-use.com/api/v3/sessions/SESSION_ID \
+```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"
```
-## Environment variable
-
-Set the key once so SDKs pick it up automatically:
-
-```bash
-export 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
-Prefer the SDK? See the [Agent docs](https://docs.browser-use.com/cloud/agent/quickstart) — the SDK has all API endpoints available as methods, including `client.browsers.create()`.
+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 Python
-pip install browser-use-sdk
-```
-```bash TypeScript
-npm install browser-use-sdk
+```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 quick start](https://docs.browser-use.com/cloud/agent/quickstart) wraps this loop — `runs.create()` then `runs.waitForCompletion()` / `runs.wait_for_completion()` — for TypeScript and Python.
# API key
Source: https://docs.browser-use.com/cloud/api-v2-overview
@@ -3046,66 +2125,3 @@ pip install browser-use-sdk
```bash TypeScript
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..3a2b3937e 100644
--- a/docs/cloud/llms.txt
+++ b/docs/cloud/llms.txt
@@ -1,15 +1,35 @@
-# Browser Use Cloud SDK
+# Browser Use Cloud
-> Browser Use Cloud is a managed API for AI browser automation. Send a natural-language task, get structured results back. SDKs for Python and TypeScript. Always use API v3 — v2 is legacy and uses different method names. Auth via `X-Browser-Use-API-Key` header (keys start with `bu_`).
+> Browser Use Cloud has two products on the same managed browser
+> infrastructure. **Agent** accepts a natural-language goal and completes the
+> web task. **Browser** gives Playwright, Puppeteer, and other remote CDP
+> clients direct control of a cloud browser. Both include stealth, residential
+> proxies, profiles, and live observability. Auth uses
+> `X-Browser-Use-API-Key` (keys start with `bu_`).
- 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
-- 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.
+- OpenAPI spec (v4): https://docs.browser-use.com/cloud/openapi/v4.json
- 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.
-**Always use v3.** v2 is legacy with different method names and should not be used for new projects.
+**Choose API V4 for hard, high-accuracy tasks.** It is the recommended Agent API for new integrations and works especially well for long, complex workflows.
+
+**Choose API V2 for simple tasks when extremely low cost or predictable speed matters more than accuracy.** V2 accuracy is substantially lower than V4.
+
+Browser Use ranks #1 on the [Odysseys benchmark](https://odysseysbench.com/leaderboard). Use the benchmark when accuracy is the deciding factor.
+
+**Stopping standalone browsers:** Do not use `client.close()`,
+`browser.close()`, or a dropped CDP connection as the API V4 stop operation.
+Keep the browser session ID returned by `POST /api/v4/browsers`, then call
+`PATCH /api/v4/browsers/{id}` with `{"action":"stop"}`. This stops billing and
+refunds unused browser time.
+
+**Current TypeScript SDK typing:** Pass `model` explicitly (use `grok-4.5` for
+the best price/accuracy balance). Whenever `browserSettings` is present, also
+pass `proxyCountryCode`: use `"us"` to keep the default or `null` to disable
+the managed proxy. New model strings can reach REST before the generated
+TypeScript union; use `POST /api/v4/runs` directly if a listed model is rejected.
Before writing code, check if `browser-use-sdk` is already installed. If so, upgrade to the latest version. If not, install it:
- Python: `pip install --upgrade browser-use-sdk`
@@ -22,43 +42,44 @@ export BROWSER_USE_API_KEY=bu_your_key_here
## Get Started
-- [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.
+- [Quick start](https://docs.browser-use.com/cloud/quickstart): Run a hosted agent or launch a cloud browser.
- [Prompt for Vibecoders](https://docs.browser-use.com/cloud/vibecoding): Complete Cloud SDK reference for AI coding agents.
## Agent
-- [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.
-- [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.
-- [Live messages](https://docs.browser-use.com/cloud/agent/streaming): Stream the agent's messages in real time to build custom UIs or monitor progress.
-- [Workspaces & files](https://docs.browser-use.com/cloud/agent/workspaces): Upload files for the agent, download files the agent creates.
-- [Deterministic rerun](https://docs.browser-use.com/cloud/agent/cache-script): Run a task once, then re-execute it for $0 LLM cost.
-- [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.
+- [Run a task](https://docs.browser-use.com/cloud/agent/quickstart): Give a high-accuracy browser agent a goal and get the result.
+- [Models](https://docs.browser-use.com/cloud/agent/models): Choose a V4 model and understand its token pricing.
+- [Structured output](https://docs.browser-use.com/cloud/agent/structured-output): Ask for JSON and validate the V4 result in your application.
+- [Sessions](https://docs.browser-use.com/cloud/agent/sessions): Continue one conversation across multiple V4 runs.
+- [Workspaces & files](https://docs.browser-use.com/cloud/agent/workspaces): Persist files across V4 runs and conversations.
+- [Scripts](https://docs.browser-use.com/cloud/agent/scripts): Save tested browser scripts in a workspace and reuse them on later runs.
+- [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop): Open the live browser, take over, then continue the same session.
+- [Observability](https://docs.browser-use.com/cloud/agent/observability): Poll ordered V4 events to monitor a run or build a custom UI.
## 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.
-- [Proxies](https://docs.browser-use.com/cloud/browser/proxies): Residential proxies in 195+ countries. On by default.
-- [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.
+- [Browser quickstart](https://docs.browser-use.com/cloud/browser/quickstart): Launch a cloud browser and connect to it from your code.
+- [Stealth](https://docs.browser-use.com/cloud/browser/stealth): Best stealth on the planet. We fork Chromium to give agents access to all websites.
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies): Route API V4 agent runs through residential or custom proxies.
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview): Watch an API V4 run in real time or record its browser.
+- [Playwright, Puppeteer, Selenium](https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium): Control a Browser Use cloud browser directly over 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.
-- [2FA](https://docs.browser-use.com/cloud/guides/2fa): Best practices for handling two-factor authentication in automated browser sessions.
+- [Profiles](https://docs.browser-use.com/cloud/guides/authentication): Reuse cookies and browser state in API V4 runs.
+- [Sync local and cloud cookies](https://docs.browser-use.com/cloud/guides/profile-sync): Sync a local login, then use it in an API V4 run.
+- [2FA](https://docs.browser-use.com/cloud/guides/2fa): Handle two-factor authentication in API V4 runs.
## More
- [FAQ](https://docs.browser-use.com/cloud/faq): Common questions and solutions.
## 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.
-- [n8n](https://docs.browser-use.com/cloud/tutorials/integrations/n8n): Use Browser Use as an HTTP node in n8n workflows.
+- [Hermes Agent](https://docs.browser-use.com/cloud/tutorials/integrations/hermes-agent): Give Hermes Agent cloud browser automation with Browser Use.
+
+## Anthropic
+- [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.
## 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.
-- [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.
+- [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.
## Legacy (v2)
- [Agent (v2)](https://docs.browser-use.com/cloud/legacy/agent): V2 agent models and file handling.
@@ -67,70 +88,8 @@ 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 v3
-- [API Reference](https://docs.browser-use.com/cloud/api-reference): Authenticate and start using the Browser Use REST API.
+## 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 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/openapi/v4.json b/docs/cloud/openapi/v4.json
index 0a15025f7..ec1f6424c 100644
--- a/docs/cloud/openapi/v4.json
+++ b/docs/cloud/openapi/v4.json
@@ -3105,9 +3105,12 @@
"enum": [
"glm-5.2",
"grok-4.5",
+ "kimi-k3",
"minimax-m3",
"claude-opus-4.7",
"claude-opus-4.8",
+ "claude-opus-5",
+ "claude-fable-5",
"claude-sonnet-5",
"gpt-5.5",
"gpt-5.6",
@@ -3751,7 +3754,7 @@
"anyOf": [
{
"type": "string",
- "maxLength": 255
+ "maxLength": 100
},
{
"type": "null"
diff --git a/docs/cloud/quickstart.mdx b/docs/cloud/quickstart.mdx
index b461a5ffc..8590383d9 100644
--- a/docs/cloud/quickstart.mdx
+++ b/docs/cloud/quickstart.mdx
@@ -1,10 +1,28 @@
---
title: Quick start
-description: "State-of-the-art AI browser automation with stealth browsers, CAPTCHA solving, residential proxies, and managed infrastructure."
+description: "Run a hosted agent or launch a cloud browser."
icon: rocket
---
-## 1. Install
+
-
-
- {/* Live browser view — liveUrl available from session creation */}
- 
+
+Give the compact context file to your coding agent.
# Models
Source: https://docs.browser-use.com/cloud/agent/models
-Pass `model` to select a model:
+Pass one of these API strings as `model` when creating a run:
+
+| Model | API string | Input | Cache read | Output | BYOK |
+| ----- | ---------- | ----: | ---------: | -----: | ---- |
+| Claude Opus 5 | `claude-opus-5` | \$6.00 | \$0.60 | \$30.00 | Anthropic |
+| Grok 4.5 | `grok-4.5` | \$2.40 | \$0.36 | \$7.20 | — |
+| GPT-5.6 | `gpt-5.6` | \$6.00 | \$0.60 | \$36.00 | OpenAI |
+| Gemini 3.5 Flash | `gemini-3.5-flash` | \$1.80 | \$0.18 | \$10.80 | Google |
+| MiniMax M3 | `minimax-m3` | \$0.36 | \$0.072 | \$1.44 | — |
-| Model | API String | Input (per 1M tokens) | Output (per 1M tokens) |
-| ----- | ---------- | --------------------- | ---------------------- |
-| Claude Sonnet 4.6 | `claude-sonnet-4.6` | \$3.60 | \$18.00 |
-| Claude Opus 4.6 | `claude-opus-4.6` | \$6.00 | \$30.00 |
-| GPT-5.4 mini | `gpt-5.4-mini` | \$0.90 | \$5.40 |
+Token prices are USD per 1 million tokens. Browser sessions
+(\$0.02/hour) and network traffic (\$5/GB managed proxy or \$0.20/GB
+proxyless/BYOP) are charged separately. See [full pricing](https://browser-use.com/pricing).
- We recommend **Claude Sonnet 4.6** (`claude-sonnet-4.6`). It's the model we optimize for the most right now.
+ **Grok 4.5** gives the best balance of price and accuracy. **MiniMax M3** is
+ the default and cheapest option; use **Claude Opus 5** when accuracy matters
+ most.
+
+ New model strings can reach the API before the TypeScript SDK's generated
+ union. If TypeScript rejects a model listed above, call `POST /api/v4/runs`
+ directly for that model.
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+from browser_use_sdk.v4 import BrowserUse
-client = AsyncBrowserUse()
-result = await client.run(
-"List the top 20 posts on Hacker News today with their points",
-model="claude-sonnet-4.6",
+client = BrowserUse()
+run = client.runs.create(
+ "Compare three project-management tools",
+ model="grok-4.5",
)
-print(result.output)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
-const result = await client.run(
- "List the top 20 posts on Hacker News today with their points",
- { model: "claude-sonnet-4.6" },
-);
-console.log(result.output);
+const run = await client.runs.create({
+ task: "Compare three project-management tools",
+ model: "grok-4.5",
+});
```
```bash curl
-curl -X POST https://api.browser-use.com/api/v3/sessions \
- -H "X-Browser-Use-API-Key: YOUR_API_KEY" \
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
-H "Content-Type: application/json" \
- -d '{"task": "List the top 20 posts on Hacker News", "model": "claude-sonnet-4.6"}'
+ -d '{"task":"Compare three PM tools","model":"grok-4.5"}'
```
+## Bring your own key
+
+Add an Anthropic, OpenAI, or Google key under **Settings → API Keys → Bring
+Your Own Key**. V4 uses it automatically for matching models; no request flag
+is needed. You pay the provider directly, plus a 0.2× Browser Use orchestration
+fee. Grok and MiniMax currently use Browser Use-managed keys.
# Structured output
Source: https://docs.browser-use.com/cloud/agent/structured-output
-Pass a Pydantic model (Python) or Zod schema (TypeScript) — `result.output` is automatically validated and converted to the typed object.
-
- TypeScript requires **Zod v4** (`npm install zod@4`). Zod v3 is not compatible.
+V4 returns `run.result` as a string. Ask for JSON only, then validate it
+client-side:
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+from browser_use_sdk.v4 import BrowserUse
from pydantic import BaseModel
-class Post(BaseModel):
-name: str
-points: int
-comments: int
+client = BrowserUse()
-class HNPosts(BaseModel):
-posts: list[Post]
+class Story(BaseModel):
+ title: str
+ points: int
-client = AsyncBrowserUse()
-result = await client.run(
-"List the top 20 posts on Hacker News today with their points",
-output_schema=HNPosts,
+run = client.runs.create(
+ 'Find the top HN story. Return only {"title":"...","points":0}.'
)
-for post in result.output.posts:
-print(f"{post.name} ({post.points} pts, {post.comments} comments)")
+run = client.runs.wait_for_completion(run.id)
+story = Story.model_validate_json(run.result or "{}")
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
import { z } from "zod";
-const Post = z.object({
- name: z.string(),
+const client = new BrowserUse();
+
+const Story = z.object({
+ title: z.string(),
points: z.number(),
- comments: z.number(),
});
-const HNPosts = z.object({
- posts: z.array(Post),
+const run = await client.runs.create({
+ task: 'Find the top HN story. Return only {"title":"...","points":0}.',
+ model: "grok-4.5",
});
-
-const client = new BrowserUse();
-const result = await client.run(
- "List the top 20 posts on Hacker News today with their points",
- { schema: HNPosts },
-);
-for (const post of result.output.posts) {
- console.log(`${post.name} (${post.points} pts, ${post.comments} comments)`);
-}
+const result = await client.runs.waitForCompletion(run.id);
+const story = Story.parse(JSON.parse(result.result ?? "{}"));
```
+V4 does not accept `output_schema` / `outputSchema`. Handle validation errors
+and retry with a [session follow-up](https://docs.browser-use.com/cloud/agent/sessions) when needed.
-# Follow-up tasks
-Source: https://docs.browser-use.com/cloud/agent/follow-up-tasks
+# Sessions
+Source: https://docs.browser-use.com/cloud/agent/sessions
-When you pass a `session_id`, the session automatically stays alive between tasks. Each task runs a new agent that reuses the same browser — the agents don't share context, but the browser state (page, cookies, tabs) carries over.
+A **session** holds the agent's conversation and can reuse its live browser.
+One session ID can contain multiple runs. Every run creates a session implicitly
+unless you pass an existing session ID.
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+
+
-client = AsyncBrowserUse()
+Pass `session_id` / `sessionId` to continue:
-# Create a session, then run tasks inside it
-session = await client.sessions.create()
+```python Python
+first = client.runs.create("Open Hacker News")
+client.runs.wait_for_completion(first.id)
-result1 = await client.run(
-"Go to amazon.com, search for laptops, and open the first result",
-session_id=session.id,
-)
-result2 = await client.run(
-"Extract the customer reviews",
-session_id=session.id,
+follow_up = client.runs.create(
+ "Now summarize the top story",
+ session_id=first.session_id,
)
-
-await client.sessions.stop(session.id)
+result = client.runs.wait_for_completion(follow_up.id)
+print(result.result)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-
-// Create a session, then run tasks inside it
-const session = await client.sessions.create();
-
-const result1 = await client.run("Go to amazon.com, search for laptops, and open the first result", {
- sessionId: session.id,
-});
-const result2 = await client.run("Extract the customer reviews", {
- sessionId: session.id,
+const first = await client.runs.create({
+ task: "Open Hacker News",
+ model: "grok-4.5",
});
+await client.runs.waitForCompletion(first.id);
-await client.sessions.stop(session.id);
+const followUp = await client.runs.create({
+ task: "Now summarize the top story",
+ model: "grok-4.5",
+ sessionId: first.sessionId,
+});
+const result = await client.runs.waitForCompletion(followUp.id);
+console.log(result.result);
```
-`sessions.create()` returns a `live_url` you can embed to watch each task execute — see [Live preview](https://docs.browser-use.com/cloud/browser/live-preview). To stream messages as each task runs, use `client.run()` with `for await` — see [Live messages](https://docs.browser-use.com/cloud/agent/streaming).
-
- Sessions time out after 15 minutes of inactivity by default. The maximum session duration is 4 hours.
+Omit the session ID for a new conversation. Pass only a [workspace
+ID](https://docs.browser-use.com/cloud/agent/workspaces) when you want a fresh conversation that keeps the
+same files.
+# Workspaces & files
+Source: https://docs.browser-use.com/cloud/agent/workspaces
-# Live messages
-Source: https://docs.browser-use.com/cloud/agent/streaming
+A **workspace** is a persistent filesystem shared by runs—even runs in
+different sessions. Use it for inputs, scripts, and generated files.
- Want a ready-made UI? See the [Chat UI tutorial](https://docs.browser-use.com/cloud/tutorials/chat-ui).
+
+
-Stream messages as the agent works — reasoning, tool calls, browser actions, and results. Each message has `role`, `type`, `summary`, `data`, and `screenshot_url`. See [List session messages](https://docs.browser-use.com/cloud/api-v3/sessions/list-session-messages) for all fields.
+## Upload and attach a file
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+from browser_use_sdk.v4 import BrowserUse
-client = AsyncBrowserUse()
-
-run = client.run("Find the top story on Hacker News")
-async for msg in run:
-print(f"[{msg.role}] {msg.summary}")
+client = BrowserUse()
+workspace = client.workspaces.create(name="research")
+uploaded = client.workspaces.upload(workspace.id, "people.csv")
-print(run.result.output)
+run = client.runs.create(
+ "Find everyone in the CSV who works at Google",
+ workspace_id=workspace.id,
+ attached_file_ids=[uploaded[0].id],
+)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
+const workspace = await client.workspaces.create({
+ name: "research",
+});
+const uploaded = await client.workspaces.upload(
+ workspace.id,
+ "people.csv",
+);
-const run = client.run("Find the top story on Hacker News");
-for await (const msg of run) {
- console.log(`[${msg.role}] ${msg.summary}`);
-}
-
-console.log(run.result.output);
+const run = await client.runs.create({
+ task: "Find everyone in the CSV who works at Google",
+ model: "grok-4.5",
+ workspaceId: workspace.id,
+ attachedFileIds: [uploaded[0].id],
+});
```
-```
-[user] Find the top story on Hacker News
-[assistant] Navigating to https://news.ycombinator.com/
-[tool] Browser Navigate: Navigated
-[assistant] Analyzing browser state
-[tool] Browser Analyze State: The top story is "Coding Agents Could Make Free Software Matter Again"
-[tool] Done Autonomous: The top story on Hacker News is "Coding Agents Could Make Free Software Matter Again"
-```
+Attachments are run-scoped. Reusing a workspace does not reattach every upload.
-## Cancel a running task
+## Retrieve created files
-Use `stop(strategy="task")` to cancel the current task without destroying the session. The session goes back to `idle` and can accept a new task.
+Ask the agent to save its output, then list the workspace:
```python Python
-run = client.run("Find the top story on Hacker News")
-async for msg in run:
-if should_cancel():
- await client.sessions.stop(run.session_id, strategy="task")
- break
-# Session is now idle — send a different task or close it
+files = client.workspaces.files(
+ workspace.id,
+ include_urls=True,
+)
+for file in files.files:
+ print(file.path, file.url)
```
```typescript TypeScript
-const run = client.run("Find the top story on Hacker News");
-for await (const msg of run) {
- if (shouldCancel()) {
-await client.sessions.stop(run.sessionId!, { strategy: "task" });
-break;
- }
+const files = await client.workspaces.files(
+ workspace.id,
+ { includeUrls: true },
+);
+for (const file of files.files) {
+ console.log(file.path, file.url);
}
-// Session is now idle — send a different task or close it
```
- `run.result` is only available **after** the iterator finishes (all messages consumed or task completes). If you break early from `async for` / `for await`, the task may still be running — call `stop(strategy="task")` to cancel it before sending a follow-up.
-
-## Manual polling
-
-If you need full control over the polling loop (e.g. custom interval, filtering):
+Download URLs expire after 60 seconds. See the [workspace API
+reference](https://docs.browser-use.com/cloud/api-v4/workspaces/list-workspace-files) for pagination and
+limits.
-```python Python
-import asyncio
-from browser_use_sdk.v3 import AsyncBrowserUse
+# Scripts
+Source: https://docs.browser-use.com/cloud/agent/scripts
-client = AsyncBrowserUse()
-session = await client.sessions.create(task="Find the top story on Hacker News")
-cursor = None
-while True:
-msgs = await client.sessions.messages(session.id, after=cursor, limit=100)
-for m in msgs.messages:
- print(f"[{m.role}] {m.summary}")
- cursor = m.id
+Scripts turn a successful browser run into a reusable
+[workspace](https://docs.browser-use.com/cloud/agent/workspaces) asset. The agent writes and tests the
+helper once. Later runs execute it first and repair it only when the site
+changes.
-s = await client.sessions.get(session.id)
-if s.status.value in ("idle", "stopped", "error", "timed_out"):
- break
-await asyncio.sleep(2)
+
+
-print(s.output)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+Create one workspace for the workflow, then use these prompts with the same
+`workspace_id` / `workspaceId`. The [run code](https://docs.browser-use.com/cloud/agent/quickstart) does not
+change.
-const client = new BrowserUse();
-const session = await client.sessions.create({
- task: "Find the top story on Hacker News",
-});
+## First run
-let cursor: string | undefined;
-while (true) {
- const msgs = await client.sessions.messages(session.id, { after: cursor, limit: 100 });
- for (const m of msgs.messages) {
-console.log(`[${m.role}] ${m.summary}`);
-cursor = m.id;
- }
+```text
+Get the top five Hacker News stories as JSON.
- const s = await client.sessions.get(session.id);
- if (["idle", "stopped", "error", "timed_out"].includes(s.status)) {
-console.log(s.output);
-break;
- }
- await new Promise((r) => setTimeout(r, 2000));
-}
+Then reproduce exactly what you did as helper functions or a script. Test it,
+save it in this workspace, and add a README with instructions for using it again.
```
-## Related
-
-- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview) — embed the browser alongside your message stream
-- [Follow-up tasks](https://docs.browser-use.com/cloud/agent/follow-up-tasks) — chain multiple tasks in one session while streaming each
+## Later runs
+```text
+Use the existing workspace script to get the top ten Hacker News stories.
+Follow its README. Only fix and retest the script if it no longer works.
+```
-# Workspaces & files
-Source: https://docs.browser-use.com/cloud/agent/workspaces
-
+This is faster and cheaper for repeated workflows, but it still starts an agent
+and uses tokens. The script is reusable and self-healing—not zero-LLM execution.
-Workspaces give your agent persistent file storage. Two patterns cover almost every use case:
+# Human in the loop
+Source: https://docs.browser-use.com/cloud/agent/human-in-the-loop
-1. **You upload a file** → agent reads it
-2. **Agent creates a file** → you download it
-## Upload a file
+Use a human checkpoint for approvals, authentication, payments, or review.
+After a run stops, get its `live_view_url` from the `browser.ready` event:
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+from browser_use_sdk.v4 import BrowserUse
-client = AsyncBrowserUse()
-workspace = await client.workspaces.create(name="my-workspace")
+client = BrowserUse()
+run = client.runs.create(
+ "Open the login page and stop for human review"
+)
+run = client.runs.wait_for_completion(run.id)
-# Upload
-await client.workspaces.upload(workspace.id, "people.csv")
+events = client.runs.events(run.id, limit=100)
+ready = next(
+ event for event in events.events
+ if event.type == "browser.ready"
+)
+print(ready.data["live_view_url"])
-# Agent can now read it
-result = await client.run(
-"Read people.csv and tell me who works at Google",
-workspace_id=workspace.id,
+# After the human finishes:
+next_run = client.runs.create(
+ "Continue from the current page",
+ session_id=run.session_id,
)
-print(result.output)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
-const workspace = await client.workspaces.create({ name: "my-workspace" });
-
-// Upload
-await client.workspaces.upload(workspace.id, "people.csv");
+const run = await client.runs.create({
+ task: "Open the login page and stop for human review",
+ model: "grok-4.5",
+});
+await client.runs.waitForCompletion(run.id);
-// Agent can now read it
-const result = await client.run(
- "Read people.csv and tell me who works at Google",
- { workspaceId: workspace.id },
+const events = await client.runs.events(run.id, {
+ limit: 100,
+});
+const ready = events.events.find(
+ (event) => event.type === "browser.ready",
);
-console.log(result.output);
-```
-
-You can upload multiple files at once:
+console.log(ready?.data.live_view_url);
-```python Python
-await client.workspaces.upload(workspace.id, "data.csv", "config.json", "image.png")
-```
-```typescript TypeScript
-await client.workspaces.upload(workspace.id, "data.csv", "config.json", "image.png");
+// After the human finishes:
+const nextRun = await client.runs.create({
+ task: "Continue from the current page",
+ model: "grok-4.5",
+ sessionId: run.sessionId,
+});
```
-## Download files
+The same session preserves the conversation and workspace and reuses the live
+browser while it is available. Treat live-view URLs as credentials.
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+# Observability
+Source: https://docs.browser-use.com/cloud/agent/observability
-client = AsyncBrowserUse()
-workspace = await client.workspaces.create(name="my-workspace")
-# Agent creates a file
-result = await client.run(
-"Go to Hacker News and save the top 3 posts as posts.json",
-workspace_id=workspace.id,
-)
+Poll `runs.events()` with the previous cursor to receive only new events:
+
+```python Python
+import time
-# Download a single file
-await client.workspaces.download(workspace.id, "posts.json", to="./posts.json")
+after = None
+while True:
+ page = client.runs.events(run.id, after=after)
+ for event in page.events:
+ print(event.type, event.data)
+ after = page.next_after if page.next_after is not None else after
-# Or download everything
-paths = await client.workspaces.download_all(workspace.id, to="./output")
-for p in paths:
-print(f"Downloaded: {p}")
+ status = client.runs.status(run.id).status.value
+ if status in {"completed", "failed", "cancelled"}:
+ break
+ time.sleep(1)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const workspace = await client.workspaces.create({ name: "my-workspace" });
-
-// Agent creates a file
-const result = await client.run(
- "Go to Hacker News and save the top 3 posts as posts.json",
- { workspaceId: workspace.id },
-);
-
-// Download a single file
-await client.workspaces.download(workspace.id, "posts.json", { to: "./posts.json" });
+let after: number | undefined;
+while (true) {
+ const page = await client.runs.events(run.id, { after });
+ for (const event of page.events) {
+ console.log(event.type, event.data);
+ }
+ after = page.nextAfter ?? after;
-// Or download everything
-const paths = await client.workspaces.downloadAll(workspace.id, { to: "./output" });
-for (const p of paths) {
- console.log(`Downloaded: ${p}`);
+ const { status } = await client.runs.status(run.id);
+ if (["completed", "failed", "cancelled"].includes(status)) break;
+ await new Promise((resolve) => setTimeout(resolve, 1000));
}
```
-## Manage workspaces
+Events cover run lifecycle, model calls, browser readiness, tool activity,
+artifacts, and completion. See [Get run events](https://docs.browser-use.com/cloud/api-v4/runs/get-run-events)
+for the complete response shape.
-```python Python
-workspace = await client.workspaces.get(workspace_id)
-updated = await client.workspaces.update(workspace_id, name="renamed")
-response = await client.workspaces.list()
-for w in response.items:
-print(w.id, w.name)
-await client.workspaces.delete(workspace_id)
-```
-```typescript TypeScript
-const workspace = await client.workspaces.get(workspaceId);
-const updated = await client.workspaces.update(workspaceId, { name: "renamed" });
-const response = await client.workspaces.list();
-for (const w of response.items) {
- console.log(w.id, w.name);
-}
-await client.workspaces.delete(workspaceId);
-```
+# Browser quickstart
+Source: https://docs.browser-use.com/cloud/browser/quickstart
-## Organize with prefixes
-Use `prefix` to organize files into directories within a workspace:
+Every browser includes stealth, proxies, live preview, and recording. Its
+**CDP URL** is a WebSocket endpoint for remotely controlling Chrome.
-```python Python
-# Upload into a subdirectory
-await client.workspaces.upload(workspace.id, "report.pdf", prefix="reports/")
+
+
-# List files in a subdirectory
-files = await client.workspaces.files(workspace.id, prefix="reports/")
-for f in files.files:
-print(f.path, f.size)
+Get an [API key](https://cloud.browser-use.com/settings?tab=api-keys&new=1) and
+export it:
-# Download only files from a subdirectory
-await client.workspaces.download_all(workspace.id, to="./output", prefix="reports/")
+```bash
+export BROWSER_USE_API_KEY=your_key
```
-```typescript TypeScript
-// Upload into a subdirectory
-await client.workspaces.upload(workspace.id, "report.pdf", { prefix: "reports/" });
-// List files in a subdirectory
-const files = await client.workspaces.files(workspace.id, { prefix: "reports/" });
-for (const f of files.files) {
- console.log(f.path, f.size);
-}
-
-// Download only files from a subdirectory
-await client.workspaces.downloadAll(workspace.id, { to: "./output", prefix: "reports/" });
-```
+## Install the SDK
-## List and delete files
+Skip this step if you use curl.
-```python Python
-# List all files
-files = await client.workspaces.files(workspace.id)
-for f in files.files:
-print(f.path, f.size)
-
-# Delete a single file
-await client.workspaces.delete_file(workspace.id, path="old-report.pdf")
-
-# Check workspace storage usage
-size = await client.workspaces.size(workspace.id)
-print(f"Used: {size.used_bytes} bytes")
+```bash Python
+pip install browser-use-sdk
```
-```typescript TypeScript
-// List all files
-const files = await client.workspaces.files(workspace.id);
-for (const f of files.files) {
- console.log(f.path, f.size);
-}
-
-// Delete a single file
-await client.workspaces.deleteFile(workspace.id, "old-report.pdf");
-
-// Check workspace storage usage
-const size = await client.workspaces.size(workspace.id);
-console.log(`Used: ${size.usedBytes} bytes`);
+```bash TypeScript
+npm install browser-use-sdk
```
-## Cloud dashboard
-
-You can also manage workspaces from [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=workspaces).
-
- Deleting a workspace permanently removes all its files. This cannot be undone.
-
-
-# Deterministic rerun
-Source: https://docs.browser-use.com/cloud/agent/cache-script
-
-
-Deterministic rerun lets you run a browser task once with a full agent, then **re-execute the same task instantly** using a cached script — no LLM, up to 99% cheaper.
-
-## Quick start
-
-Use `@{{double brackets}}` around values that can change between runs. The first call runs the full agent. Every subsequent call with the same template uses the cached script.
+## Launch a browser
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-workspace = await client.workspaces.create(name="my-scraper")
+from browser_use_sdk.v3 import BrowserUse
-# First call — agent explores, creates script (~$0.10, ~60s)
-result = await client.run(
-"Get the top @{{5}} stories from https://news.ycombinator.com as JSON",
-workspace_id=str(workspace.id),
-)
+client = BrowserUse()
+browser = client.browsers.create(proxy_country_code="us")
+print(browser.cdp_url)
-# Second call — cached script, different param ($0 LLM, ~5s)
-result2 = await client.run(
-"Get the top @{{10}} stories from https://news.ycombinator.com as JSON",
-workspace_id=str(workspace.id),
-)
+# When finished:
+client.browsers.stop(browser.id)
```
```typescript TypeScript
import { BrowserUse } from "browser-use-sdk/v3";
const client = new BrowserUse();
-const workspace = await client.workspaces.create({ name: "my-scraper" });
-
-// First call — agent explores, creates script (~$0.10, ~60s)
-const result = await client.run(
- "Get the top @{{5}} stories from https://news.ycombinator.com as JSON",
- { workspaceId: workspace.id },
-);
+const browser = await client.browsers.create({ proxyCountryCode: "us" });
+console.log(browser.cdpUrl);
-// Second call — cached script, different param ($0 LLM, ~5s)
-const result2 = await client.run(
- "Get the top @{{10}} stories from https://news.ycombinator.com as JSON",
- { workspaceId: workspace.id },
-);
+// When finished:
+await client.browsers.stop(browser.id);
```
+```bash curl
+browser=$(curl -sS https://api.browser-use.com/api/v4/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"proxyCountryCode":"us"}')
-## How it works
-
-The brackets mark which parts are parameters:
+export BROWSER_SESSION_ID=$(echo "$browser" | jq -r .id)
+export BROWSER_USE_CDP_URL=$(echo "$browser" | jq -r .cdpUrl)
+echo "$BROWSER_USE_CDP_URL"
+# When finished:
+curl -X PATCH \
+ "https://api.browser-use.com/api/v4/browsers/$BROWSER_SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action":"stop"}'
```
-"Get prices from @{{example.com}} for @{{electronics}}"
-```
-
-- `@{{example.com}}` → parameter 1
-- `@{{electronics}}` → parameter 2
-The system strips the values to create a **template**: `"Get prices from @{{}} for @{{}}"`.
-Template `"Get prices from @{{}} for @{{}}"` is hashed to a unique ID like `a7f3b2c1`.
-The system checks the workspace for `scripts/a7f3b2c1.py`.
-If no script exists, the full agent runs your task. After completing it, the agent saves a standalone Python script that reproduces the result deterministically — no AI needed.
-If the script exists, it runs directly with the new parameter values. No agent, no LLM. Just the script in a sandbox with browser and proxy.
+ `browser.close()`, disconnecting CDP, or `client.close()` does not stop the
+ managed browser. Use `client.browsers.stop(browser.id)` or call
+ `PATCH /api/v4/browsers/{id}` with `{"action":"stop"}`.
-## Auto-detection
+
+
-// Same task again — cached
-result = await client.run(
- "Get the current Bitcoin price from coinmarketcap.com @{{}}",
- { workspaceId: workspace.id },
-);
-```
+Set `browser_settings` / `browserSettings` when you create a V4 run to choose
+another country:
-### Multiple parameters
+ The current TypeScript SDK type requires `proxyCountryCode` whenever
+ `browserSettings` is present. Use `"us"` to keep the default, or `null` to
+ disable the managed proxy.
```python Python
-result = await client.run(
-"Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{Germany,France,Japan}}",
-workspace_id=str(workspace.id),
-)
+from browser_use_sdk.v4 import BrowserUse
-# Different countries — cached
-result2 = await client.run(
-"Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{US,UK,Brazil}}",
-workspace_id=str(workspace.id),
+client = BrowserUse()
+run = client.runs.create(
+ "Get the iPhone 16 price on amazon.de",
+ browser_settings={"proxyCountryCode": "de"},
)
```
```typescript TypeScript
-let result = await client.run(
- "Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{Germany,France,Japan}}",
- { workspaceId: workspace.id },
-);
+import { BrowserUse } from "browser-use-sdk/v4";
-// Different countries — cached
-result = await client.run(
- "Go to https://help.netflix.com/en/node/24926/ax and get subscription prices for @{{US,UK,Brazil}}",
- { workspaceId: workspace.id },
-);
+const client = new BrowserUse();
+const run = await client.runs.create({
+ task: "Get the iPhone 16 price on amazon.de",
+ model: "grok-4.5",
+ browserSettings: { proxyCountryCode: "de" },
+});
+```
+```bash curl
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Get the iPhone 16 price on amazon.de",
+ "browserSettings":{"proxyCountryCode":"de"}}'
```
-### Force enable / disable
+## Disable proxies
-```python Python
-# Force-enable without brackets
-result = await client.run(
-"Get the top stories from Hacker News",
-workspace_id=str(workspace.id),
-cache_script=True,
-)
+Pass `null` for QA or internal sites that do not need a residential proxy:
-# Force-disable even with brackets
-result = await client.run(
-"Explain what @{{templates}} means in Jinja",
-workspace_id=str(workspace.id),
-cache_script=False,
+```python Python
+run = client.runs.create(
+ "Test my staging site",
+ browser_settings={"proxyCountryCode": None},
)
```
```typescript TypeScript
-// Force-enable without brackets
-let result = await client.run(
- "Get the top stories from Hacker News",
- { workspaceId: workspace.id, cacheScript: true },
-);
-
-// Force-disable even with brackets
-result = await client.run(
- "Explain what @{{templates}} means in Jinja",
- { workspaceId: workspace.id, cacheScript: false },
-);
+const run = await client.runs.create({
+ task: "Test my staging site",
+ model: "grok-4.5",
+ browserSettings: { proxyCountryCode: null },
+});
```
-## Inspecting cached scripts
+## Custom proxy
-You can download and inspect the scripts the agent created:
+Custom HTTP and SOCKS5 proxies are available on paid plans:
```python Python
-files = await client.workspaces.files(workspace.id, prefix="scripts/")
-for f in files.files:
-print(f"{f.path} ({f.size} bytes)")
-
-# Download a script to inspect it
-await client.workspaces.download(workspace.id, "scripts/a7f3b2c1.py", to="./my_script.py")
+run = client.runs.create(
+ "Check the account dashboard",
+ browser_settings={
+ "customProxy": {
+ "host": "proxy.example.com",
+ "port": 8080,
+ "username": "user",
+ "password": "pass",
+ "ignoreCertErrors": False,
+ }
+ },
+)
```
```typescript TypeScript
-const files = await client.workspaces.files(workspace.id, { prefix: "scripts/" });
-for (const f of files.files) {
- console.log(`${f.path} (${f.size} bytes)`);
-}
+const run = await client.runs.create({
+ task: "Check the account dashboard",
+ model: "grok-4.5",
+ browserSettings: {
+ proxyCountryCode: "us",
+ customProxy: {
+ host: "proxy.example.com",
+ port: 8080,
+ username: "user",
+ password: "pass",
+ ignoreCertErrors: false,
+ },
+ },
+});
```
-## Auto-healing
-
-Cached scripts can break when a website changes its layout, adds new elements, or alters its structure. Auto-healing detects these failures and automatically regenerates the script.
+A custom proxy overrides `proxyCountryCode` and must be passed again when a
+follow-up provisions a new browser. See the [Create run
+reference](https://docs.browser-use.com/cloud/api-v4/runs/create-run) for the complete settings object.
-### How it works
-
-When a cached script runs, the system validates its output:
+# Live preview & recording
+Source: https://docs.browser-use.com/cloud/browser/live-preview
-1. **Fast checks** (no LLM) — detects empty results, error fields in JSON, or exception keywords in output.
-2. **LLM judge** — if fast checks pass, a lightweight model validates whether the output looks correct for the original task.
-3. **Heal** — if validation fails, the full agent re-runs the task and saves an updated script.
-Auto-healing is **limited to 1 attempt per run** to prevent runaway costs. If the healed script also fails, the output is returned as-is.
+The `browser.ready` event contains the live browser URL:
-### Cost impact
+```python Python
+from browser_use_sdk.v4 import BrowserUse
-| Scenario | LLM cost |
-|----------|----------|
-| Cached script succeeds | **$0** |
-| Cached script fails, auto-heals | ~$0.05–1.00 (one full agent run) |
-| Healed script also fails | Same as above (returns best-effort output) |
+client = BrowserUse()
+run = client.runs.create("Find the top Hacker News story")
+run = client.runs.wait_for_completion(run.id)
-Auto-healing is enabled by default for all cached scripts. No configuration needed.
+events = client.runs.events(run.id, limit=100)
+ready = next(
+ event for event in events.events
+ if event.type == "browser.ready"
+)
+print(ready.data["live_view_url"])
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v4";
-## Cost comparison
+const client = new BrowserUse();
+const run = await client.runs.create({
+ task: "Find the top Hacker News story",
+ model: "grok-4.5",
+});
+await client.runs.waitForCompletion(run.id);
-| | LLM cost | Browser + proxy | Time |
-|---|---|---|---|
-| First call (agent) | ~$0.05–1.00 | Yes | ~30–120s |
-| Cached calls | **$0** | Yes | ~3–10s |
+const events = await client.runs.events(run.id, {
+ limit: 100,
+});
+const ready = events.events.find(
+ (event) => event.type === "browser.ready",
+);
+console.log(ready?.data.live_view_url);
+```
-The browser and proxy still run for cached calls (the script may need them), so there is a small infrastructure cost per execution. LLM cost drops to zero.
+Poll [run events](https://docs.browser-use.com/cloud/agent/observability) if you need the URL as soon as
+the browser starts.
+## Embed the live browser
-# Human in the loop
-Source: https://docs.browser-use.com/cloud/agent/human-in-the-loop
+```html
+
+```
+The URL is hosted on `live.browser-use.com`. Add that origin to your
+Content Security Policy's `frame-src` directive when needed. Treat the URL as
+a credential: anyone with it can interact with the active browser.
-## Use cases
-- Human enters payment info or approves a transaction, agent handles the rest
-- Human navigates a complex auth flow, then hands back to agent
-- Human reviews what the agent did before the agent continues
+## Recording
- Sessions time out after 15 minutes of inactivity. The maximum session duration is 4 hours. If the human needs more time, send a lightweight follow-up task (e.g. "wait") to reset the inactivity timer.
+Enable recording when the run creates its browser:
-## Flow
+```python Python
+run = client.runs.create(
+ "Test the checkout flow",
+ browser_settings={"record": True},
+)
+```
+```typescript TypeScript
+const run = await client.runs.create({
+ task: "Test the checkout flow",
+ model: "grok-4.5",
+ browserSettings: { proxyCountryCode: "us", record: true },
+});
+```
+```bash curl
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Test checkout","browserSettings":{"record":true}}'
+```
-1. Create a session — it stays alive automatically when you pass `session_id` to `run()`
-2. Run an agent task
-3. Human interacts with the live browser
-4. Send a new follow-up task
+The MP4 becomes available in the Dashboard after the browser stops. API runs
+default to recording off, and Zero Data Retention projects never record.
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+# Playwright, Puppeteer, Selenium
+Source: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium
-client = AsyncBrowserUse()
-# 1. Create a session
-session = await client.sessions.create()
-print(f"Live view: {session.live_url}")
+Every browser 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.
-# 2. Agent does the first part
-result = await client.run(
-"Go to amazon.com and search for noise cancelling headphones",
-session_id=session.id,
-)
-print(result.output)
+ This page is for direct browser control. To give an AI agent a goal instead,
+ [create an API V4 run](https://docs.browser-use.com/cloud/agent/quickstart).
-# 3. Human opens live_url and picks a product
-input("Press Enter after you've selected a product in the live view...")
+## 1. Create a browser
-# 4. Agent continues where the human left off
-result = await client.run(
-"Get the details of the selected product — name, price, and rating",
-session_id=session.id,
-)
-print(result.output)
+```bash
+session=$(curl -sS https://api.browser-use.com/api/v4/browsers \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"proxyCountryCode":"us"}')
-# Clean up
-await client.sessions.stop(session.id)
+export BROWSER_SESSION_ID=$(echo "$session" | jq -r .id)
+export BROWSER_USE_CDP_URL=$(echo "$session" | jq -r .cdpUrl)
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import * as readline from "readline";
-const client = new BrowserUse();
+## 2. Connect over CDP
-// 1. Create a session
-const session = await client.sessions.create();
-console.log(`Live view: ${session.liveUrl}`);
+### Playwright
-// 2. Agent does the first part
-const searchResult = await client.run(
- "Go to amazon.com and search for noise cancelling headphones",
- { sessionId: session.id },
-);
-console.log(searchResult.output);
+```python Python
+import os
+from playwright.sync_api import sync_playwright
-// 3. Human opens liveUrl and picks a product
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-await new Promise((resolve) =>
- rl.question("Press Enter after you've selected a product in the live view...", resolve),
-);
-rl.close();
+with sync_playwright() as p:
+ browser = p.chromium.connect_over_cdp(os.environ["BROWSER_USE_CDP_URL"])
+ page = browser.contexts[0].pages[0]
+ page.goto("https://example.com")
+ print(page.title())
+```
+```typescript TypeScript
+import { chromium } from "playwright";
-// 4. Agent continues where the human left off
-const result = await client.run(
- "Get the details of the selected product — name, price, and rating",
- { sessionId: session.id },
+const browser = await chromium.connectOverCDP(
+ process.env.BROWSER_USE_CDP_URL!,
);
-console.log(result.output);
-
-// Clean up
-await client.sessions.stop(session.id);
+const page = browser.contexts()[0].pages()[0];
+await page.goto("https://example.com");
+console.log(await page.title());
```
+### Puppeteer
+```typescript
+import puppeteer from "puppeteer-core";
-# Introduction Stealth
-Source: https://docs.browser-use.com/cloud/browser/stealth
+const browser = await puppeteer.connect({
+ browserWSEndpoint: process.env.BROWSER_USE_CDP_URL!,
+});
+const [page] = await browser.pages();
+await page.goto("https://example.com");
+console.log(await page.title());
+```
+### Selenium
-See [how we perform in the hardest stealth benchmark](https://browser-use.com/posts/stealth-benchmark).
+Selenium's `debugger_address` only supports local `host:port` connections.
+Use Playwright or Puppeteer for remote CDP over WebSocket.
-## What's included
+## 3. Stop the browser
-Every cloud browser session runs in a hardened Chromium fork with stealth enabled by default — no configuration needed.
+```bash
+curl -X PATCH \
+ "https://api.browser-use.com/api/v4/browsers/$BROWSER_SESSION_ID" \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"action":"stop"}'
+```
-- **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.
+ `browser.close()` and disconnecting CDP do not stop the managed browser.
+ Call `PATCH /api/v4/browsers/{id}` with `{"action":"stop"}`.
-## Residential proxies
+See [Create browser session](https://docs.browser-use.com/cloud/api-v4/browsers/create-browser-session) and
+[Update browser session](https://docs.browser-use.com/cloud/api-v4/browsers/update-browser-session) for
+every browser setting and response field.
-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.
+# Profiles
+Source: https://docs.browser-use.com/cloud/guides/authentication
-# Proxies
-Source: https://docs.browser-use.com/cloud/browser/proxies
+A profile persists cookies, local storage, and login state across browsers.
+Log in once, save the profile, then reuse it to start future browsers already
+logged in.
+
+
-A US residential proxy is active by default on every browser. To route through a different country, set `proxy_country_code`. See the [API reference](https://docs.browser-use.com/cloud/api-v3/browsers/create-browser-session) for all supported country codes.
+Create or select one under [Dashboard → Profiles](https://cloud.browser-use.com/settings?tab=profiles),
+then pass its ID in V4 browser settings:
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-browser = await client.browsers.create(proxy_country_code="de")
-print(browser.cdp_url) # ws://...
-print(browser.live_url) # debug view
+from browser_use_sdk.v4 import BrowserUse
-# With an agent:
-# result = await client.run("Get the price of iPhone 16 on amazon.de", proxy_country_code="de")
+client = BrowserUse()
+run = client.runs.create(
+ "Open my account dashboard and summarize it",
+ browser_settings={"profileId": "YOUR_PROFILE_ID"},
+)
+result = client.runs.wait_for_completion(run.id)
+print(result.result)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
-const browser = await client.browsers.create({ proxyCountryCode: "de" });
-console.log(browser.cdpUrl);
-console.log(browser.liveUrl);
-
-// With an agent:
-// const result = await client.run("Get the price of iPhone 16 on amazon.de", { proxyCountryCode: "de" });
+const run = await client.runs.create({
+ task: "Open my account dashboard and summarize it",
+ model: "grok-4.5",
+ browserSettings: {
+ profileId: "YOUR_PROFILE_ID",
+ proxyCountryCode: "us",
+ },
+});
+const result = await client.runs.waitForCompletion(run.id);
+console.log(result.result);
+```
+```bash curl
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Summarize my account dashboard",
+ "browserSettings":{"profileId":"YOUR_PROFILE_ID"}}'
```
-## Disable proxies
+Use one profile per end user. Follow-ups in the same [session](https://docs.browser-use.com/cloud/agent/sessions)
+reuse the live browser; later sessions can load the same profile again.
-If your use case does not need proxies, for example QA testing.
+For the fastest setup, [sync an existing local login](https://docs.browser-use.com/cloud/guides/profile-sync).
-```python Python
-browser = await client.browsers.create(proxy_country_code=None)
+# Sync local and cloud cookies
+Source: https://docs.browser-use.com/cloud/guides/profile-sync
-# With an agent:
-# result = await client.run("Go to http://localhost:3000", proxy_country_code=None)
-```
-```typescript TypeScript
-const browser = await client.browsers.create({ proxyCountryCode: null });
-// With an agent:
-// const result = await client.run("Go to http://localhost:3000", { proxyCountryCode: null });
-```
+Run the profile sync helper:
-## Custom proxy
+```bash
+export BROWSER_USE_API_KEY=your_key
+curl -fsSL https://browser-use.com/profile.sh | sh
+```
-Bring your own proxy server (HTTP or SOCKS5).
+Choose the accounts to sync, then use the returned profile ID:
```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+from browser_use_sdk.v4 import BrowserUse
-client = AsyncBrowserUse()
-browser = await client.browsers.create(
-custom_proxy={
- "host": "proxy.example.com",
- "port": 8080,
- "username": "user",
- "password": "pass",
-},
+client = BrowserUse()
+run = client.runs.create(
+ "Check my LinkedIn messages",
+ browser_settings={"profileId": "YOUR_PROFILE_ID"},
)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+import { BrowserUse } from "browser-use-sdk/v4";
const client = new BrowserUse();
-const browser = await client.browsers.create({
- customProxy: {
-host: "proxy.example.com",
-port: 8080,
-username: "user",
-password: "pass",
+const run = await client.runs.create({
+ task: "Check my LinkedIn messages",
+ model: "grok-4.5",
+ browserSettings: {
+ profileId: "YOUR_PROFILE_ID",
+ proxyCountryCode: "us",
},
});
```
+The profile supplies cookies and local storage without putting credentials in
+the prompt. Re-sync when the site's login expires.
-# Live preview & recording
-Source: https://docs.browser-use.com/cloud/browser/live-preview
+# 2FA
+Source: https://docs.browser-use.com/cloud/guides/2fa
- Want a ready-made UI? See the [Chat UI tutorial](https://docs.browser-use.com/cloud/tutorials/chat-ui).
+The most reliable options are a saved profile or a human checkpoint.
-`liveUrl` is returned on session creation.
+## Reuse a logged-in profile
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
+[Sync your local login](https://docs.browser-use.com/cloud/guides/profile-sync), then load that profile in
+the run:
-client = AsyncBrowserUse()
-session = await client.sessions.create(task="Check how many GitHub stars browser-use has")
-print(session.live_url)
+```python Python
+run = client.runs.create(
+ "Download my latest invoice",
+ browser_settings={"profileId": "YOUR_PROFILE_ID"},
+)
```
```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const session = await client.sessions.create({
- task: "Check how many GitHub stars browser-use has",
+const run = await client.runs.create({
+ task: "Download my latest invoice",
+ model: "grok-4.5",
+ browserSettings: {
+ profileId: "YOUR_PROFILE_ID",
+ proxyCountryCode: "us",
+ },
});
-console.log(session.liveUrl);
```
-`liveUrl` is also returned when creating a standalone browser session:
+This avoids another 2FA challenge while the site's cookies remain valid.
+
+## Let a human take over
+
+Ask the first run to stop at the 2FA screen, get its `live_view_url` from the
+[`browser.ready` event](https://docs.browser-use.com/cloud/agent/human-in-the-loop), and have the user enter
+the code. Then continue with the same session:
```python Python
-browser = await client.browsers.create()
-print(browser.live_url)
+first = client.runs.create(
+ "Open the login page and stop at the 2FA prompt",
+)
+client.runs.wait_for_completion(first.id)
+
+next_run = client.runs.create(
+ "Continue after login and download the invoice",
+ session_id=first.session_id,
+)
```
```typescript TypeScript
-const browser = await client.browsers.create();
-console.log(browser.liveUrl);
+const first = await client.runs.create({
+ task: "Open the login page and stop at the 2FA prompt",
+ model: "grok-4.5",
+});
+await client.runs.waitForCompletion(first.id);
+
+const nextRun = await client.runs.create({
+ task: "Continue after login and download the invoice",
+ model: "grok-4.5",
+ sessionId: first.sessionId,
+});
```
-## Embed live browser into your app
+See [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) for retrieving and
+embedding the live browser URL. Never put passwords or TOTP secrets directly
+in a prompt.
-Useful for human interaction or to see live what's happening.
+# Claude Code
+Source: https://docs.browser-use.com/cloud/tutorials/integrations/claude-code
-```html
-
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) is Anthropic's agentic coding tool that runs in the terminal. Add Browser Use and it gets full cloud browser automation — anti-detect profiles, CAPTCHA solving, residential proxies in 195+ countries, persistent profiles, and stealth browsing.
+
+## Setup
+
+**1. Install the CLI**
+
+```bash
+uv tool install browser-use
```
-The live URL is hosted on `live.browser-use.com`. If your app sets a Content Security Policy, add it to your `frame-src` directive:
+**2. Verify the installation**
+```bash
+browser-use doctor
```
-Content-Security-Policy: frame-src 'self' https://live.browser-use.com;
+
+**3. Register the skill**
+
+Register the Browser Use skill with the installed CLI:
+
+```bash
+browser-use skill install
```
-For responsive sizing, use CSS instead of fixed dimensions:
+**4. Authenticate for cloud browsers**
-```html
-
+Sign up at [cloud.browser-use.com](https://cloud.browser-use.com), then authenticate:
+
+```bash
+browser-use auth login
```
-## Customize
+Or let Claude Code provision a free API key itself — see [Agent Self-Registration](#agent-self-registration) below.
-Append query parameters to the `liveUrl`:
+**5. Use it**
-| Parameter | Values | Description |
-|-----------|--------|-------------|
-| `theme` | `light`, `dark` (default) | Light or dark mode |
-| `ui` | `false` | Hide the browser chrome (URL bar, tabs) |
+Claude Code uses its bash tool to run CLI commands directly:
```
-https://live.browser-use.com?wss=...&theme=light
-https://live.browser-use.com?wss=...&ui=false
+> Use browser-use to open github.com/trending and summarize the top repos
```
-## Recording
+For the complete CLI reference and Python execution examples, see the [Browser Use CLI docs](https://docs.browser-use.com/open-source/browser-use-cli).
- `waitForRecording` / `wait_for_recording` requires the **v3 SDK** (`from browser_use_sdk.v3 import AsyncBrowserUse` / `import { BrowserUse } from "browser-use-sdk/v3"`).
+## Agent Self-Registration
-Enable recording to get an MP4 video of the browser session. Only available when the agent actually opens a browser — tasks answered without browsing produce no recording. If you run multiple tasks in the same session (with `keep_alive`), you may get multiple recordings.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-result = await client.run(
-"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
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const result = await client.run("Check how many GitHub stars browser-use has", {
- enableRecording: true,
-});
-
-// Waits up to 15s for recording to be ready. Returns [] if no browser was opened.
-const urls = await client.sessions.waitForRecording(result.id);
-for (const url of urls) {
- console.log(url); // presigned MP4 download URL
-}
-```
-
-For standalone browser sessions, pass `enable_recording` when creating the browser and retrieve the URL after stopping it:
-
-```python Python
-browser = await client.browsers.create(enable_recording=True)
-# ... use the browser via CDP ...
-stopped = await client.browsers.stop(browser.id)
-print(stopped.recording_url) # presigned MP4 download URL
-```
-```typescript TypeScript
-const browser = await client.browsers.create({ enableRecording: true });
-// ... use the browser via CDP ...
-const stopped = await client.browsers.stop(browser.id);
-console.log(stopped.recordingUrl); // presigned MP4 download URL
-```
-
- Recording URLs are presigned and **expire after 1 hour**. Download or serve the recording promptly. If you need to access it later, save the MP4 to your own storage.
-
-## Related
-
-- [Live messages](https://docs.browser-use.com/cloud/agent/streaming) — stream the agent's messages alongside the live browser view
-- [Follow-up tasks](https://docs.browser-use.com/cloud/agent/follow-up-tasks) — chain tasks in one session while watching live
-
-
-
-# Playwright, Puppeteer, Selenium
-Source: https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium
-
-
-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.
-
-## 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 is automatically stopped when the WebSocket disconnects
-```
-```typescript TypeScript
-import { chromium } from "playwright";
-
-const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";
-
-const browser = await chromium.connectOverCDP(WSS_URL);
-const page = browser.contexts()[0].pages()[0];
-await page.goto("https://example.com");
-console.log(await page.title());
-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
-
-| 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, get a `cdp_url`, and connect with Playwright or Puppeteer.
-
-### Playwright
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-from playwright.async_api import async_playwright
-
-client = AsyncBrowserUse()
-browser = await client.browsers.create()
-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()
-
-await client.browsers.stop(browser.id)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import { chromium } from "playwright";
-
-const client = new BrowserUse();
-const browser = await client.browsers.create();
-console.log(browser.cdpUrl); // https://uuid.cdpN.browser-use.com
-console.log(browser.liveUrl); // https://live.browser-use.com?wss=...
-
-const pwBrowser = await chromium.connectOverCDP(browser.cdpUrl);
-const page = pwBrowser.contexts()[0].pages()[0];
-await page.goto("https://example.com");
-console.log(await page.title());
-await pwBrowser.close();
-
-await client.browsers.stop(browser.id);
-```
-
-### Puppeteer
-
-```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 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();
-
-await client.browsers.stop(browser.id);
-```
-
- Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
-
-
-# Profiles
-Source: https://docs.browser-use.com/cloud/guides/authentication
-
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-profile = await client.profiles.create(name="user-id-1")
-# or search existing
-# 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)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const profile = await client.profiles.create({ name: "user-id-1" });
-// or search existing
-// 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,
-});
-console.log(result.output);
-
-// Always stop the session to persist profile state
-await client.sessions.stop(session.id);
-```
-
-View your profile IDs at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=profiles).
-
-## Manage profiles
-
-```python Python
-# Create
-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)
-
-# Search by name
-response = await client.profiles.list(query="user-id-1")
-profile = response.items[0] # first match
-
-# Get one by ID
-profile = await client.profiles.get(profile_id)
-
-# Update
-await client.profiles.update(profile_id, name="renamed")
-
-# Delete
-await client.profiles.delete(profile_id)
-```
-```typescript TypeScript
-// Create
-const profile = await client.profiles.create({ name: "work-account" });
-
-// List all
-const response = await client.profiles.list();
-for (const p of response.items) {
- console.log(p.id, p.name);
-}
-
-// Search by name
-const results = await client.profiles.list({ query: "user-id-1" });
-const found = results.items[0]; // first match
-
-// Get one by ID
-const fetched = await client.profiles.get(profileId);
-
-// Update
-await client.profiles.update(profileId, { name: "renamed" });
-
-// Delete
-await client.profiles.delete(profileId);
-```
-
-## Usage patterns
-
-- **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.
-
-
-# Sync local and cloud cookies
-Source: https://docs.browser-use.com/cloud/guides/profile-sync
+Claude Code can provision its own Browser Use API key autonomously — no human interaction needed. The free tier includes unlimited browser hours, free proxies in 195+ countries, persistent browser profiles, CAPTCHA solving, and stealth browsing at zero cost.
+Install the Browser Use CLI and skill:
```bash
-export BROWSER_USE_API_KEY=your_key && curl -fsSL https://browser-use.com/profile.sh | sh
-```
-
-This opens a browser where you select which accounts to sync. After syncing, you receive a `profile_id` to use in your tasks.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-session = await client.sessions.create(profile_id="your_synced_profile_id")
-result = await client.run("Check my LinkedIn messages", session_id=session.id)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-const session = await client.sessions.create({ profileId: "your_synced_profile_id" });
-const result = await client.run("Check my LinkedIn messages", {
- sessionId: session.id,
-});
-```
-
-
-# 2FA
-Source: https://docs.browser-use.com/cloud/guides/2fa
-
-
-Sites with 2FA block automated logins. Here are four approaches — pick the one that fits your setup.
-
-| Approach | Best for | Complexity |
-|---|---|---|
-| [Profiles (login once)](#1-profiles--login-once-reuse-cookies) | Sites with long-lived cookies | Lowest |
-| [Human in the loop](#2-human-in-the-loop) | One-off tasks, complex auth flows | Low |
-| [Agent Mail](#3-agent-mail) | Email-based 2FA, end-client automation | Medium |
-| [TOTP secret in prompt](#4-totp-secret-in-prompt) | Authenticator app 2FA (Google Authenticator, Authy) | Medium |
-
----
-
-## 1. Profiles — login once, reuse cookies
-
-Login manually once (or let the agent do it), then save the browser state as a profile. Future sessions reuse the cookies — no 2FA prompt as long as the cookies are valid.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-
-# Create a profile and a session
-profile = await client.profiles.create(name="my-account")
-session = await client.sessions.create(profile_id=profile.id)
-print(f"Live view: {session.live_url}")
-
-# Option A: human logs in via live view
-input("Log in and complete 2FA in the live view, then press Enter...")
-
-# Option B: let the agent log in
-# await client.run("Log in to example.com with user@example.com / password123", session_id=session.id)
-
-# Stop the session — this saves cookies to the profile
-await client.sessions.stop(session.id)
-
-# Next time: reuse the profile, no 2FA needed
-session = await client.sessions.create(profile_id=profile.id)
-result = await client.run("Go to example.com/dashboard and get my balance", session_id=session.id)
-print(result.output)
-await client.sessions.stop(session.id)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import * as readline from "readline";
-
-const client = new BrowserUse();
-
-// Create a profile and a session
-const profile = await client.profiles.create({ name: "my-account" });
-const session = await client.sessions.create({ profileId: profile.id });
-console.log(`Live view: ${session.liveUrl}`);
-
-// Option A: human logs in via live view
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-await new Promise((resolve) => rl.question("Log in and complete 2FA in the live view, then press Enter...", resolve));
-rl.close();
-
-// Option B: let the agent log in
-// await client.run("Log in to example.com with user@example.com / password123", { sessionId: session.id });
-
-// Stop the session — this saves cookies to the profile
-await client.sessions.stop(session.id);
-
-// Next time: reuse the profile, no 2FA needed
-const newSession = await client.sessions.create({ profileId: profile.id });
-const result = await client.run("Go to example.com/dashboard and get my balance", { sessionId: newSession.id });
-console.log(result.output);
-await client.sessions.stop(newSession.id);
-```
-
- Cookies expire. Some sites stay logged in for months, others expire daily. If your sessions start hitting login pages again, re-authenticate and save the profile.
-
- Always call `sessions.stop()` after you're done — profile state is only saved when the session ends cleanly.
-
----
-
-## 2. Human in the loop
-
-Let the agent navigate to the login page, then a human takes over to complete 2FA via the live browser view. The agent continues after.
-
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
-session = await client.sessions.create()
-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,
-)
-
-# Human completes 2FA in the live view
-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,
-)
-print(result.output)
-await client.sessions.stop(session.id)
+uv tool install browser-use
+browser-use skill install
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import * as readline from "readline";
-const client = new BrowserUse();
-const session = await client.sessions.create();
-console.log(`Live view: ${session.liveUrl}`);
+Claude Code can follow the [REST flow](https://docs.browser-use.com/cloud/agent-signup#rest-flow) to request and verify a challenge, then put the returned key in its shell environment:
-// Agent navigates to login
-await client.run(
- "Go to example.com/login and enter username user@example.com and password mypassword, then stop before 2FA",
- { sessionId: session.id },
-);
-
-// Human completes 2FA in the live view
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-await new Promise((resolve) => rl.question("Complete 2FA in the live view, then press Enter...", resolve));
-rl.close();
-
-// Agent continues
-const result = await client.run(
- "You are now logged in. Go to the dashboard and export the monthly report",
- { sessionId: session.id },
-);
-console.log(result.output);
-await client.sessions.stop(session.id);
+```bash
+export BROWSER_USE_API_KEY=bu_...
+browser-use auth status
```
-See [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) for more patterns.
+### Claim the account (optional)
----
+If the human wants to see the account in the dashboard later, use the [claim endpoint](https://docs.browser-use.com/cloud/agent-signup#claim-the-account). The returned claim URL is valid for 1 hour.
-## 3. Agent Mail
+# Claude Managed Agents
+Source: https://docs.browser-use.com/cloud/tutorials/integrations/claude-managed-agents
-When 2FA sends a code via email, the agent can read it automatically using Agent Mail — a built-in email inbox for each session.
-Agent Mail is **enabled by default** (`agentmail=True`). Each session gets a unique email address (`session.agentmail_email`). The agent can send and receive emails during the task.
+[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents) run on Anthropic's hosted platform. Install the `browser-use` CLI in the agent's environment and it can drive a stealth cloud browser — with proxies, CAPTCHA solving, live view, and recording. Your API key stays in a credential vault; the model never sees it.
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
+The sandbox can't run a local browser, so the agent starts a named Browser Use Cloud browser and drives it with `browser-use <<'PY'` Python snippets.
-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
-)
-print(result.output)
-```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
+## 1. Create an environment
-const client = new BrowserUse();
+Pre-install the CLI so it's ready at session start (no runtime install).
-const 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
-);
-console.log(result.output);
+```yaml
+name: browser-env
+config:
+ type: cloud
+ packages:
+ pip:
+ - browser-use
+ networking:
+ type: limited
+ allowed_hosts: ["*.browser-use.com"]
+ allow_package_managers: true
```
-### For end-client automation
-
-If you're automating on behalf of your users and they need to receive 2FA codes:
-
-1. **Email forwarding:** Have your client set up an email forwarding rule — forward all emails from the service (e.g., `noreply@bank.com`) to a dedicated inbox (a Gmail address or an Agent Mail address).
-2. **Give the agent access:** The agent reads the forwarded 2FA code from that inbox during the task.
-
-This way, your client's real email stays private — the agent only sees the forwarded verification emails.
+## 2. Create a credential vault
-### Connect external email via Composio
+Store your key as an environment variable so the CLI reads it and the model never does. Get one at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=api-keys&new=1).
-You can also give the agent access to an existing Gmail account using [Composio](https://composio.dev) in the Browser Use dashboard. Once connected, the agent can read emails directly from that account to retrieve 2FA codes.
+| Field | Value |
+| ----- | --------------------- |
+| Type | Environment variable |
+| Name | `BROWSER_USE_API_KEY` |
+| Value | `bu_...` |
----
-
-## 4. TOTP secret in prompt
-
-If the site uses an authenticator app (Google Authenticator, Authy, etc.), you can pass the TOTP secret to the agent. Our agent can execute Python code, so it uses the `pyotp` library to generate fresh 6-digit codes on the fly.
-
-When you set up 2FA on a site, instead of only scanning the QR code, also copy the **secret key** (usually shown as "manual entry" or "can't scan the QR code?"). This is a long base32 string like `JBSWY3DPEHPK3PXP`.
+## 3. Create the agent
-```python Python
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-client = AsyncBrowserUse()
+Tell it to use the CLI in cloud mode.
-# The TOTP secret from your authenticator setup — NOT the 6-digit code
-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:
-
-import pyotp
-totp = pyotp.TOTP("{totp_secret}")
-code = totp.now()
-
-Enter the generated code.
-""",
-)
-print(result.output)
+```yaml
+name: browser agent
+model:
+ id: claude-opus-4-8
+description: Drives a stealth cloud browser with the Browser Use CLI.
+system: |
+ You are a browser agent. Use the `browser-use` CLI to complete web tasks.
+ Never launch a local browser in this sandbox. Start a named cloud browser:
+ browser-use <<'PY'
+ start_remote_daemon("managed")
+ PY
+ Then run browser work through the same name:
+ BU_NAME=managed browser-use <<'PY'
+ new_tab("https://example.com")
+ print(page_info())
+ PY
+ Your BROWSER_USE_API_KEY is in the environment; never print it.
+tools:
+ - type: agent_toolset_20260401 # shell access so the agent can run the CLI
+ default_config:
+ enabled: true
+ permission_policy:
+ type: always_allow
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-
-const client = new BrowserUse();
-// The TOTP secret from your authenticator setup — NOT the 6-digit code
-const totpSecret = "JBSWY3DPEHPK3PXP";
+## 4. Start a session and send a task
-const result = await client.run(
- `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("${totpSecret}")
- code = totp.now()
+The Console only observes; kick the agent off with a `user.message` event.
- Enter the generated code.`,
-);
-console.log(result.output);
+```bash
+curl -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "anthropic-version: 2023-06-01" \
+ -H "anthropic-beta: managed-agents-2026-04-01" \
+ -H "content-type: application/json" \
+ -d '{"events":[{"type":"user.message","content":[{"type":"text",
+ "text":"Get the top 5 Hacker News stories with their links."}]}]}'
```
-This works because the Browser Use agent can execute Python code as part of its task. The agent runs `pyotp.TOTP(secret).now()` to generate a time-based 6-digit code, then types it into the 2FA field.
-
-### Where to find TOTP secrets
-
-- **1Password**: Edit item → One-Time Password → Show secret
-- **Google Authenticator**: During setup, click "Can't scan it?" to see the key
-- **Authy**: Export via desktop app settings
-- **Most sites**: Look for "manual entry" or "setup key" during 2FA enrollment
-
----
-
-## Which approach should I use?
+## 5. Watch it run
-Start with **Profiles** — log in once, reuse cookies. If cookies expire frequently, add **TOTP secret in prompt** for fully automated re-login.
-Use **Profiles** with one profile per user. For initial login, use **Human in the loop** — your user logs in once via the live view, then the agent reuses the session. For email 2FA, set up **Agent Mail** with email forwarding from your user.
-Use **Agent Mail** (enabled by default). For end-client scenarios, have them forward 2FA emails to a dedicated inbox.
-Use **TOTP secret in prompt** — the agent generates codes via pyotp, no human intervention needed.
+The agent starts a named cloud browser, runs Python helper snippets through `browser-use`, then returns the result. The session shows up in [cloud.browser-use.com](https://cloud.browser-use.com) → **Remote Browsers** with a **Live View** and an **mp4 recording**.
+ Always use a cloud browser — the Managed Agents sandbox has no GUI, so a local
+ browser won't start. Cloud mode also gives you stealth, residential proxies,
+ live view, and recording.
# OpenClaw
Source: https://docs.browser-use.com/cloud/tutorials/integrations/openclaw
@@ -1798,733 +1293,314 @@ Open `~/.openclaw/openclaw.json` and add a `browser-use` profile:
```json5
{
- browser: {
-enabled: true,
-defaultProfile: "browser-use",
-remoteCdpTimeoutMs: 3000,
-remoteCdpHandshakeTimeoutMs: 5000,
-profiles: {
- "browser-use": {
- cdpUrl: "wss://connect.browser-use.com?apiKey=
- {/* Chat column */}
-
- );
-}
+```bash
+export BROWSER_USE_API_KEY=bu_...
+browser-use auth status
```
----
+### Claim the account (optional)
-## Summary
+If the human wants to see the account in the dashboard later, use the [claim endpoint](https://docs.browser-use.com/cloud/agent-signup#claim-the-account). The returned claim URL is valid for 1 hour.
-| Method | Purpose |
-|--------|---------|
-| `client.sessions.create()` | Create a session (returns `liveUrl` immediately) |
-| `client.run()` | Send a task and stream messages with `for await` |
-| `client.sessions.stop()` | Stop the current task |
-| `client.sessions.waitForRecording()` | Get MP4 recording URLs |
+# Agent Sign Up for Browser Use
+Source: https://docs.browser-use.com/cloud/agent-signup
-# Grow Therapy provider search
-Source: https://docs.browser-use.com/cloud/tutorials/grow-therapy-compare
+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.
-This tutorial builds a provider search tool for [Grow Therapy](https://www.growtherapy.com) — a therapy marketplace that handles insurance credentialing for providers. We combine [structured output](https://docs.browser-use.com/cloud/agent/structured-output) with [deterministic rerun](https://docs.browser-use.com/cloud/agent/cache-script) to build a fast, repeatable search pipeline.
+## REST flow
-## What you'll build
+### 1. Request a challenge
-A script that:
-1. Searches Grow Therapy's provider directory with filters (location, insurance, specialty)
-2. Extracts therapist profiles with ratings and availability
-3. Caches the search so you can sweep across geographies or specialties instantly
+```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):
-## Setup
+```json
+{
+ "email": "user@example.com",
+ "name": "User Name"
+}
+```
-```python Python
-import asyncio
-import json
-from pydantic import BaseModel
-from browser_use_sdk.v3 import AsyncBrowserUse
+Response:
-client = AsyncBrowserUse()
+```json
+{
+ "challenge_id": "uuid",
+ "challenge_text": "..."
+}
```
-```typescript TypeScript
-import { BrowserUse } from "browser-use-sdk/v3";
-import { z } from "zod";
-const client = new BrowserUse();
-```
+### 2. Solve the challenge
-## 1. Define the output schema
+Read `challenge_text` and solve the math problem. Return the answer as a string with two decimal places, for example `"144.00"`.
-```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
-
-class ProviderSearch(BaseModel):
-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(),
- })),
- totalFound: z.number().nullable(),
- location: z.string(),
- specialty: z.string(),
-});
+### 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"}'
```
-## 2. Create a workspace
+Request body:
-```python Python
-workspace = await client.workspaces.create(name="grow-therapy-search")
+```json
+{
+ "challenge_id": "uuid",
+ "answer": "144.00"
+}
```
-```typescript TypeScript
-const workspace = await client.workspaces.create({ name: "grow-therapy-search" });
+
+Response:
+
+```json
+{
+ "api_key": "bu_..."
+}
```
-## 3. Search for providers
+Use the returned key for Browser Use Cloud API requests.
-```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,
-)
+For example, create an API V4 run:
-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()
+```bash
+curl https://api.browser-use.com/api/v4/runs \
+ -H "X-Browser-Use-API-Key: bu_..." \
+ -H "Content-Type: application/json" \
+ -d '{"task":"Find the top Hacker News story"}'
```
-```typescript TypeScript
-const 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.",
- { workspaceId: workspace.id, schema: ProviderSearch },
-);
-for (const p of result.output.providers) {
- console.log(`${p.name} (${p.title})`);
- console.log(` Specialties: ${p.specialties.join(", ")}`);
- console.log(` Rating: ${p.rating}`);
- console.log(` Next available: ${p.nextAvailable}`);
-}
-```
+See the [API V4 quick start](https://docs.browser-use.com/cloud/agent/quickstart).
-## 4. Sweep across locations and specialties
+## Claim the account
-After the first run caches the search flow, sweep across different parameters at $0 LLM cost:
+If a human wants to see the agent-created account in the dashboard later, the agent can create a claim link:
-```python Python
-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")
+```bash
+curl -X POST https://api.browser-use.com/cloud/signup/claim \
+ -H "X-Browser-Use-API-Key: bu_..."
```
-```typescript TypeScript
-const locations = ["Los Angeles", "Chicago", "Houston", "Miami"];
-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`);
- }
+Response:
+
+```json
+{
+ "claim_url": "https://..."
}
```
----
-
-## Summary
-
-| Step | What happens | Cost |
-|------|-------------|------|
-| First search | Agent navigates Grow Therapy, caches the flow | ~$0.10 |
-| 12 cached sweeps (4 cities x 3 specialties) | Script reruns with new params | **$0 LLM each** |
-| Site layout change | [Auto-healing](https://docs.browser-use.com/cloud/agent/cache-script#auto-healing) regenerates the script | ~$0.10 |
+The claim URL is valid for 1 hour.
-Therapy platforms have dynamic UIs that can change frequently. [Auto-healing](https://docs.browser-use.com/cloud/agent/cache-script#auto-healing) ensures your cached scripts stay working without manual maintenance.
+## CLI usage
-## Next steps
+Agents with shell access can use the Browser Use CLI after the REST flow returns an API key:
-- [Structured output](https://docs.browser-use.com/cloud/agent/structured-output) — Learn more about extracting typed data with Pydantic and Zod schemas.
-- [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) — Let a human review or interact with the browser mid-task, useful for auth flows or approving results before continuing.
-- [Deterministic rerun](https://docs.browser-use.com/cloud/agent/cache-script) — Deep dive into how caching and auto-healing work.
+```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.
# FAQ
Source: https://docs.browser-use.com/cloud/faq
@@ -2532,19 +1608,30 @@ Source: https://docs.browser-use.com/cloud/faq
## Which model should I use?
-- **Claude Opus 4.6** (`claude-opus-4.6`) — most capable. Use for the hardest tasks that need maximum accuracy.
-- **Claude Sonnet 4.6** (`claude-sonnet-4.6`, default) — best balance of capability and cost. Use for complex multi-step workflows.
-- **GPT-5.4 mini** (`gpt-5.4-mini`) — fast and efficient. Good for simple, well-defined tasks.
+- **Claude Opus 5** (`claude-opus-5`) — maximum intelligence for difficult, long-horizon work.
+- **GPT-5.6** (`gpt-5.6`) — fast on complex tasks.
+- **Gemini 3.5 Flash** (`gemini-3.5-flash`) — fast for simpler tasks.
+- **MiniMax M3** (`minimax-m3`, default) — cheapest for simple and high-volume tasks.
+
+See [Models](https://docs.browser-use.com/cloud/agent/models) for the complete V4 picker and pricing.
## How do I get the live browser URL?
-`live_url` is returned on session creation. Embed it in an iframe or open it in a browser.
+The V4 run's `browser.ready` event contains `live_view_url`. Embed it in an iframe or open it in a browser.
```python
-session = await client.sessions.create(task="Go to example.com")
-print(session.live_url)
+from browser_use_sdk.v4 import BrowserUse
+
+client = BrowserUse()
+created = client.runs.create("Go to example.com")
+client.runs.wait_for_completion(created.id)
+events = client.runs.events(created.id, limit=100)
+ready = next(event for event in events.events if event.type == "browser.ready")
+print(ready.data["live_view_url"])
```
+Poll events until `browser.ready` appears if you need the URL while the run is still active. See [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop) for a complete flow.
+
## Getting blocked by a website
Stealth and proxies are active by default. If you're still getting blocked:
@@ -2558,25 +1645,21 @@ If it still doesn't work, contact support inside the [Cloud Dashboard](https://c
The SDK auto-retries 429 responses with exponential backoff. If persistent, you may need more concurrent sessions — contact support.
-## v2 vs v3 — which should I use?
-
-**v3 is the recommendation for everything.** It's a premium agent (not available in open source) that is significantly more capable than v2:
+## V2 or V4 — which should I use?
-- **Much better at complex tasks** and multi-step workflows
-- **Much better at large data extraction**
-- **File system** with persistent memory across tasks
-- **Task scheduling** with 1,000+ integrations (Gmail, Slack, and more)
+Use **V4** for difficult tasks where accuracy matters. It supports:
-v2 is the closest to the open-source experience — pure browser automation, nothing else. If the open source already works great for your use case, v2 is the natural fit. For everything else, use v3.
+- Run-focused API with a cheap status polling endpoint
+- Conversation sessions with follow-ups
+- Persistent workspaces and turn-scoped file attachments
+- Incremental events for custom UIs and monitoring
+- Per-run cost totals, cost caps, and optional judgement
-```python
-# v3 (recommended)
-from browser_use_sdk.v3 import AsyncBrowserUse
-
-# v2 (simple browser-only tasks)
-from browser_use_sdk.v2 import AsyncBrowserUse
-```
+Use **V2** when tasks are simple and your priority is very low cost and
+predictable speed. Its accuracy is substantially lower.
+See Browser Use at #1 on the
+[Odysseys benchmark](https://odysseysbench.com/leaderboard).
# Agent (v2)
Source: https://docs.browser-use.com/cloud/legacy/agent
@@ -2587,7 +1670,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 +1703,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 +1744,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 +1767,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
```
@@ -2727,7 +1809,6 @@ console.log(run.result?.output); // final result after iteration
| `op_vault_id` | `str` | 1Password vault ID for auto-fill credentials and 2FA. |
| `metadata` | `dict[str, str]` | Custom metadata attached to the task. |
-
# Public share links (v2)
Source: https://docs.browser-use.com/cloud/legacy/public-share
@@ -2743,7 +1824,6 @@ const share = await client.sessions.createShare(session.id);
console.log(share.shareUrl);
```
-
# Skills
Source: https://docs.browser-use.com/cloud/legacy/skills
@@ -2767,8 +1847,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 +1869,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)
```
@@ -2831,7 +1911,6 @@ const result = await client.marketplace.execute(skillId, { parameters: { ... } }
See [Pricing](https://browser-use.com/pricing) for skill costs.
-
# 1Password & 2FA
Source: https://docs.browser-use.com/cloud/guides/1password
@@ -2862,9 +1941,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 +1954,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 +1965,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"],
},
);
```
@@ -2912,7 +1991,6 @@ When the agent encounters a login form:
The agent never sees your actual credentials. The actual username, password, and 2FA codes are filled in programmatically — keeping your secrets hidden from the AI model.
-
# Secrets
Source: https://docs.browser-use.com/cloud/guides/secrets
@@ -2924,9 +2002,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 +2014,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,30 +2026,29 @@ 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-reference
+Source: https://docs.browser-use.com/cloud/api-v4-overview
## Authentication
@@ -2987,42 +2064,44 @@ Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/sett
## Base URL
```
-https://api.browser-use.com/api/v3
+https://api.browser-use.com/api/v4
```
-## Quick example
+## The core loop
-```bash Create a session
-curl -X POST https://api.browser-use.com/api/v3/sessions \
+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 Get session result (replace SESSION_ID)
-curl https://api.browser-use.com/api/v3/sessions/SESSION_ID \
+```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"
```
-## Environment variable
-
-Set the key once so SDKs pick it up automatically:
-
-```bash
-export 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
-Prefer the SDK? See the [Agent docs](https://docs.browser-use.com/cloud/agent/quickstart) — the SDK has all API endpoints available as methods, including `client.browsers.create()`.
+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 Python
-pip install browser-use-sdk
-```
-```bash TypeScript
-npm install browser-use-sdk
+```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 quick start](https://docs.browser-use.com/cloud/agent/quickstart) wraps this loop — `runs.create()` then `runs.waitForCompletion()` / `runs.wait_for_completion()` — for TypeScript and Python.
# API key
Source: https://docs.browser-use.com/cloud/api-v2-overview
@@ -3046,66 +2125,3 @@ pip install browser-use-sdk
```bash TypeScript
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..3a2b3937e 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -1,15 +1,35 @@
-# Browser Use Cloud SDK
+# Browser Use Cloud
-> Browser Use Cloud is a managed API for AI browser automation. Send a natural-language task, get structured results back. SDKs for Python and TypeScript. Always use API v3 — v2 is legacy and uses different method names. Auth via `X-Browser-Use-API-Key` header (keys start with `bu_`).
+> Browser Use Cloud has two products on the same managed browser
+> infrastructure. **Agent** accepts a natural-language goal and completes the
+> web task. **Browser** gives Playwright, Puppeteer, and other remote CDP
+> clients direct control of a cloud browser. Both include stealth, residential
+> proxies, profiles, and live observability. Auth uses
+> `X-Browser-Use-API-Key` (keys start with `bu_`).
- 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
-- 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.
+- OpenAPI spec (v4): https://docs.browser-use.com/cloud/openapi/v4.json
- 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.
-**Always use v3.** v2 is legacy with different method names and should not be used for new projects.
+**Choose API V4 for hard, high-accuracy tasks.** It is the recommended Agent API for new integrations and works especially well for long, complex workflows.
+
+**Choose API V2 for simple tasks when extremely low cost or predictable speed matters more than accuracy.** V2 accuracy is substantially lower than V4.
+
+Browser Use ranks #1 on the [Odysseys benchmark](https://odysseysbench.com/leaderboard). Use the benchmark when accuracy is the deciding factor.
+
+**Stopping standalone browsers:** Do not use `client.close()`,
+`browser.close()`, or a dropped CDP connection as the API V4 stop operation.
+Keep the browser session ID returned by `POST /api/v4/browsers`, then call
+`PATCH /api/v4/browsers/{id}` with `{"action":"stop"}`. This stops billing and
+refunds unused browser time.
+
+**Current TypeScript SDK typing:** Pass `model` explicitly (use `grok-4.5` for
+the best price/accuracy balance). Whenever `browserSettings` is present, also
+pass `proxyCountryCode`: use `"us"` to keep the default or `null` to disable
+the managed proxy. New model strings can reach REST before the generated
+TypeScript union; use `POST /api/v4/runs` directly if a listed model is rejected.
Before writing code, check if `browser-use-sdk` is already installed. If so, upgrade to the latest version. If not, install it:
- Python: `pip install --upgrade browser-use-sdk`
@@ -22,43 +42,44 @@ export BROWSER_USE_API_KEY=bu_your_key_here
## Get Started
-- [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.
+- [Quick start](https://docs.browser-use.com/cloud/quickstart): Run a hosted agent or launch a cloud browser.
- [Prompt for Vibecoders](https://docs.browser-use.com/cloud/vibecoding): Complete Cloud SDK reference for AI coding agents.
## Agent
-- [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.
-- [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.
-- [Live messages](https://docs.browser-use.com/cloud/agent/streaming): Stream the agent's messages in real time to build custom UIs or monitor progress.
-- [Workspaces & files](https://docs.browser-use.com/cloud/agent/workspaces): Upload files for the agent, download files the agent creates.
-- [Deterministic rerun](https://docs.browser-use.com/cloud/agent/cache-script): Run a task once, then re-execute it for $0 LLM cost.
-- [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.
+- [Run a task](https://docs.browser-use.com/cloud/agent/quickstart): Give a high-accuracy browser agent a goal and get the result.
+- [Models](https://docs.browser-use.com/cloud/agent/models): Choose a V4 model and understand its token pricing.
+- [Structured output](https://docs.browser-use.com/cloud/agent/structured-output): Ask for JSON and validate the V4 result in your application.
+- [Sessions](https://docs.browser-use.com/cloud/agent/sessions): Continue one conversation across multiple V4 runs.
+- [Workspaces & files](https://docs.browser-use.com/cloud/agent/workspaces): Persist files across V4 runs and conversations.
+- [Scripts](https://docs.browser-use.com/cloud/agent/scripts): Save tested browser scripts in a workspace and reuse them on later runs.
+- [Human in the loop](https://docs.browser-use.com/cloud/agent/human-in-the-loop): Open the live browser, take over, then continue the same session.
+- [Observability](https://docs.browser-use.com/cloud/agent/observability): Poll ordered V4 events to monitor a run or build a custom UI.
## 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.
-- [Proxies](https://docs.browser-use.com/cloud/browser/proxies): Residential proxies in 195+ countries. On by default.
-- [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.
+- [Browser quickstart](https://docs.browser-use.com/cloud/browser/quickstart): Launch a cloud browser and connect to it from your code.
+- [Stealth](https://docs.browser-use.com/cloud/browser/stealth): Best stealth on the planet. We fork Chromium to give agents access to all websites.
+- [Proxies](https://docs.browser-use.com/cloud/browser/proxies): Route API V4 agent runs through residential or custom proxies.
+- [Live preview & recording](https://docs.browser-use.com/cloud/browser/live-preview): Watch an API V4 run in real time or record its browser.
+- [Playwright, Puppeteer, Selenium](https://docs.browser-use.com/cloud/browser/playwright-puppeteer-selenium): Control a Browser Use cloud browser directly over 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.
-- [2FA](https://docs.browser-use.com/cloud/guides/2fa): Best practices for handling two-factor authentication in automated browser sessions.
+- [Profiles](https://docs.browser-use.com/cloud/guides/authentication): Reuse cookies and browser state in API V4 runs.
+- [Sync local and cloud cookies](https://docs.browser-use.com/cloud/guides/profile-sync): Sync a local login, then use it in an API V4 run.
+- [2FA](https://docs.browser-use.com/cloud/guides/2fa): Handle two-factor authentication in API V4 runs.
## More
- [FAQ](https://docs.browser-use.com/cloud/faq): Common questions and solutions.
## 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.
-- [n8n](https://docs.browser-use.com/cloud/tutorials/integrations/n8n): Use Browser Use as an HTTP node in n8n workflows.
+- [Hermes Agent](https://docs.browser-use.com/cloud/tutorials/integrations/hermes-agent): Give Hermes Agent cloud browser automation with Browser Use.
+
+## Anthropic
+- [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.
## 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.
-- [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.
+- [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.
## Legacy (v2)
- [Agent (v2)](https://docs.browser-use.com/cloud/legacy/agent): V2 agent models and file handling.
@@ -67,70 +88,8 @@ 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 v3
-- [API Reference](https://docs.browser-use.com/cloud/api-reference): Authenticate and start using the Browser Use REST API.
+## 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 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/openapi/v4.json b/docs/openapi/v4.json
index 0a15025f7..ec1f6424c 100644
--- a/docs/openapi/v4.json
+++ b/docs/openapi/v4.json
@@ -3105,9 +3105,12 @@
"enum": [
"glm-5.2",
"grok-4.5",
+ "kimi-k3",
"minimax-m3",
"claude-opus-4.7",
"claude-opus-4.8",
+ "claude-opus-5",
+ "claude-fable-5",
"claude-sonnet-5",
"gpt-5.5",
"gpt-5.6",
@@ -3751,7 +3754,7 @@
"anyOf": [
{
"type": "string",
- "maxLength": 255
+ "maxLength": 100
},
{
"type": "null"
-
-
- {/* Live browser view — liveUrl available from session creation */}
-