> ## Documentation Index
> Fetch the complete documentation index at: https://browseruse-0aece648-pricing-docs-rework.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Infrastructure

> Direct Chrome DevTools Protocol (CDP) access to stealth browsers. Connect via WebSocket URL or SDK with Playwright, Puppeteer, or Selenium.

The Browser API gives you a raw Chrome DevTools Protocol (CDP) connection to Browser Use's stealth infrastructure. No agent — you write the automation code, we provide the undetectable browser with proxies and CAPTCHA handling.

There are two ways to connect:

* **WebSocket URL** — single `wss://` URL, no SDK needed. Pass config as query params, browser auto-stops on disconnect.
* **SDK** — create a browser via the API, get a `cdp_url`, connect with your framework of choice.

## WebSocket URL (no SDK)

Connect to a cloud browser with a single WebSocket URL. All configuration is passed as query parameters — no SDK or REST calls needed.

<Tip>
  This is the simplest way to get a CDP connection. Just point Playwright, Puppeteer, or any CDP client at the URL.
</Tip>

### Playwright

<CodeGroup>
  ```python Python theme={null}
  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 theme={null}
  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
  ```
</CodeGroup>

### Puppeteer

```typescript theme={null}
import puppeteer from "puppeteer-core";

const WSS_URL = "wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us";

const browser = await puppeteer.connect({ browserWSEndpoint: WSS_URL });
const [page] = await browser.pages();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();
// Browser is automatically stopped when the WebSocket disconnects
```

### Query parameters

| Parameter              | Type     | Description                                                 |
| ---------------------- | -------- | ----------------------------------------------------------- |
| `apiKey`               | `string` | **Required.** Your Browser Use API key.                     |
| `proxyCountryCode`     | `string` | Proxy country code (e.g. `us`, `de`, `jp`). 195+ countries. |
| `profileId`            | `string` | Load a saved browser profile (cookies, localStorage).       |
| `timeout`              | `int`    | Session timeout in minutes. Max: 240 (4 hours).             |
| `browserScreenWidth`   | `int`    | Browser width in pixels.                                    |
| `browserScreenHeight`  | `int`    | Browser height in pixels.                                   |
| `customProxy.host`     | `string` | Custom proxy host.                                          |
| `customProxy.port`     | `int`    | Custom proxy port.                                          |
| `customProxy.username` | `string` | Username for the custom proxy.                              |
| `customProxy.password` | `string` | Password for the custom proxy.                              |

### How it works

The browser is automatically created when you connect and automatically stopped when the WebSocket disconnects. No need to call any API to start or stop the browser.

<Tip>
  CDP discovery endpoints are also exposed over HTTPS for tools that use HTTP auto-discovery — e.g. `https://connect.browser-use.com/json/version?apiKey=YOUR_API_KEY`.
</Tip>

## SDK

### Create a browser session

<CodeGroup>
  ```python Python theme={null}
  from browser_use_sdk import AsyncBrowserUse

  client = AsyncBrowserUse()
  browser = await client.browsers.create(proxy_country_code="us")
  print(browser.cdp_url)   # ws://...
  print(browser.live_url)  # debug view
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";

  const client = new BrowserUse();
  const browser = await client.browsers.create({ proxyCountryCode: "us" });
  console.log(browser.cdpUrl);
  console.log(browser.liveUrl);
  ```
</CodeGroup>

### Connect with Playwright

<CodeGroup>
  ```python Python theme={null}
  from playwright.async_api import async_playwright
  from browser_use_sdk import AsyncBrowserUse

  client = AsyncBrowserUse()
  browser = await client.browsers.create()

  async with async_playwright() as p:
      b = await p.chromium.connect_over_cdp(browser.cdp_url)
      page = b.contexts[0].pages[0]
      await page.goto("https://example.com")
      print(await page.title())
      await b.close()

  await client.browsers.stop(browser.id)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";
  import { chromium } from "playwright";

  const client = new BrowserUse();
  const browser = await client.browsers.create();

  const pw = await chromium.connectOverCDP(browser.cdpUrl);
  const page = pw.contexts()[0].pages()[0];
  await page.goto("https://example.com");
  console.log(await page.title());
  await pw.close();

  await client.browsers.stop(browser.id);
  ```
</CodeGroup>

### Connect with Puppeteer

```typescript theme={null}
import puppeteer from "puppeteer-core";
import { BrowserUse } from "browser-use-sdk";

const client = new BrowserUse();
const browser = await client.browsers.create();

const pw = await puppeteer.connect({ browserWSEndpoint: browser.cdpUrl });
const [page] = await pw.pages();
await page.goto("https://example.com");
console.log(await page.title());
await pw.close();

await client.browsers.stop(browser.id);
```

### Connect with Selenium

```python theme={null}
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
browser = await client.browsers.create()

options = Options()
options.debugger_address = browser.cdp_url.replace("ws://", "").replace("/devtools/browser/", "")
driver = webdriver.Chrome(options=options)
driver.get("https://example.com")
print(driver.title)
driver.quit()

await client.browsers.stop(browser.id)
```

### Manage sessions

<CodeGroup>
  ```python Python theme={null}
  from browser_use_sdk import AsyncBrowserUse

  client = AsyncBrowserUse()

  # List active sessions
  sessions = await client.browsers.list()

  # Get a specific session
  session = await client.browsers.get(browser_id)

  # Stop a session
  await client.browsers.stop(browser_id)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";

  const client = new BrowserUse();

  const sessions = await client.browsers.list();
  const session = await client.browsers.get(browserId);
  await client.browsers.stop(browserId);
  ```
</CodeGroup>

<Warning>
  Always stop browser sessions when done. Sessions left running will continue to incur charges until the timeout expires.
</Warning>

### Parameters

| Parameter               | Type          | Description                                                                                           |
| ----------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `profile_id`            | `str`         | Load a saved browser profile (cookies, localStorage).                                                 |
| `proxy_country_code`    | `str`         | Proxy country code (e.g. `us`, `de`, `jp`). 195+ countries.                                           |
| `timeout`               | `int`         | Session timeout in minutes. Max: 240 (4 hours).                                                       |
| `browser_screen_width`  | `int`         | Browser width in pixels.                                                                              |
| `browser_screen_height` | `int`         | Browser height in pixels.                                                                             |
| `custom_proxy`          | `CustomProxy` | Bring your own proxy (HTTP or SOCKS5). See [Proxies](/cloud/guides/proxies-and-stealth#custom-proxy). |

See [Models & Pricing](/cloud/pricing) for browser session and proxy costs.