### Run Python Example

Source: https://github.com/browserbase/playbook/blob/main/README.md

Execute a Python example. Ensure your virtual environment is activated before running.

```bash
python path/to/example.py
```

--------------------------------

### Setup Python Virtual Environment and Install Dependencies

Source: https://github.com/browserbase/playbook/blob/main/README.md

Set up a Python virtual environment and install dependencies using pip. This ensures a clean environment for Python examples. Requires Python 3.8+.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```

--------------------------------

### Run Node.js Example

Source: https://github.com/browserbase/playbook/blob/main/README.md

Execute a Node.js TypeScript example using tsx. Replace 'path/to/example.ts' with the actual path to your script.

```bash
npx tsx path/to/example.ts
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/browserbase/playbook/blob/main/node/README.md

Install the necessary npm packages for the project.

```bash
npm install
```

--------------------------------

### Configure Browserbase Environment Variables

Source: https://github.com/browserbase/playbook/blob/main/README.md

Copy the example environment file and edit it with your Browserbase credentials and optional API keys for services like Stagehand. These variables are essential for authenticating and running examples.

```bash
cp .env.example .env
```

```dotenv
BROWSERBASE_PROJECT_ID=your_project_id
BROWSERBASE_API_KEY=your_api_key
OPENAI_API_KEY=your_openai_key  # Optional, used for Stagehand
ANTHROPIC_API_KEY=your_anthropic_key  # Optional, used for Stagehand
```

--------------------------------

### Clone Browserbase Playbook Repository

Source: https://github.com/browserbase/playbook/blob/main/README.md

Clone the Browserbase playbook repository to your local machine. This is the first step to accessing the code examples.

```bash
git clone https://github.com/browserbase/playbook.git
cd playbook
```

--------------------------------

### Get Project Usage

Source: https://context7.com/browserbase/playbook/llms.txt

Retrieves a list of projects and their associated usage data.

```APIDOC
## Get project list and usage (TypeScript)

### Description
Fetches a list of all projects and the usage statistics for a specific project.

### Method
GET

### Endpoint
`/v1/projects`
`/v1/projects/{projectId}/usage`

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project to get usage for.

### Request Example
```typescript
async function getProjectUsage() {
  const headers = { "X-BB-API-Key": process.env.BROWSERBASE_API_KEY! };
  const projects = await fetch("https://api.browserbase.com/v1/projects", { headers }).then((r) => r.json());
  const usage = await fetch(
    `https://api.browserbase.com/v1/projects/${process.env.BROWSERBASE_PROJECT_ID}/usage`,
    { headers }
  ).then((r) => r.json());
  return { projects, usage };
}
```

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.
- **usage** (object) - An object containing usage statistics for the specified project.
```

--------------------------------

### Inspect Available Actions with `page.observe()` (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Returns a list of actionable elements or descriptions visible on the current page, useful for dynamic exploration before acting. Requires Browserbase environment setup.

```typescript
import { Stagehand } from "@browserbasehq/stagehand";

async function main() {
  const stagehand = new Stagehand({ env: "BROWSERBASE" });
  await stagehand.init();
  const page = stagehand.page;

  await page.goto("https://www.browserbase.com/contact");

  const fields = await page.observe({
    instruction: "What fields can be filled in?",
  });
  console.log(fields);
  // Output: [{ description: 'Name input field', selector: 'input[name="name"]' }, ...]

  await stagehand.close();
}

main();
```

--------------------------------

### Get Session Details, Logs, and Recording

Source: https://context7.com/browserbase/playbook/llms.txt

Fetches comprehensive information about a specific session, including its details, logs, and recording data. Requires a session ID.

```typescript
async function inspectSession(sessionId: string) {
  const headers = { "X-BB-API-Key": process.env.BROWSERBASE_API_KEY! };
  const base = `https://api.browserbase.com/v1/sessions/${sessionId}`;

  const [details, logs, recording] = await Promise.all([
    fetch(base, { headers }).then((r) => r.json()),
    fetch(`${base}/logs`, { headers }).then((r) => r.json()),
    fetch(`${base}/recording`, { headers }).then((r) => r.json()),
  ]);

  console.log("Details:", details);
  console.log("Logs:", logs);
  console.log("Recording:", recording);
}

```

--------------------------------

### Perform Actions with Natural Language using `page.act()` (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Translates plain-English instructions into Playwright actions, allowing for safe string interpolation with variables. Requires Browserbase environment setup.

```typescript
import { Stagehand } from "@browserbasehq/stagehand";
import boxen from "boxen";
import chalk from "chalk";

async function main() {
  const stagehand = new Stagehand({ env: "BROWSERBASE" });
  await stagehand.init();
  const page = stagehand.page;

  console.log(
    boxen(
      `Session: ${chalk.blue(`https://browserbase.com/sessions/${stagehand.browserbaseSessionID}`)}`,
      { title: "Browserbase", padding: 1, margin: 2 }
    )
  );

  await page.goto("https://www.browserbase.com/contact");

  // Fill out the contact form using natural language
  await page.act({
    action: "Fill in the fields with name: %name% email: %email% phone: %phone% message: %message%",
    variables: {
      name: "Jane Doe",
      email: "jane.doe@example.com",
      phone: "5551234567",
      message: "I am interested in the Scale plan.",
    },
  });

  await page.waitForTimeout(2000);
  await stagehand.close();
}

main();
```

--------------------------------

### Get the live debugger URL

Source: https://context7.com/browserbase/playbook/llms.txt

Returns a URL for the Browserbase DevTools live view, accessible while the session is active.

```APIDOC
## Get the live debugger URL (TypeScript)

### Description
Returns a URL for the Browserbase DevTools live view, accessible while the session is active.

### Method
GET

### Endpoint
`/v1/sessions/{sessionId}/debug`

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to get the debugger URL for.

### Request Example
```typescript
import Browserbase from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function getLiveDebugURL(sessionId: string) {
  const res = await fetch(
    `https://api.browserbase.com/v1/sessions/${sessionId}/debug`,
    { headers: { "X-BB-API-Key": process.env.BROWSERBASE_API_KEY! } }
  );
  const json = await res.json();
  console.log("Debugger URL:", json.debuggerUrl);
  return json.debuggerUrl;
}

// Usage:
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
});
await getLiveDebugURL(session.id);
```

### Response
#### Success Response (200)
- **debuggerUrl** (string) - The URL for the live debugger view.
```

--------------------------------

### Get Project List and Usage Information

Source: https://context7.com/browserbase/playbook/llms.txt

Retrieves a list of all projects associated with the API key and fetches the usage statistics for a specific project. Requires the project ID.

```typescript
async function getProjectUsage() {
  const headers = { "X-BB-API-Key": process.env.BROWSERBASE_API_KEY! };
  const projects = await fetch("https://api.browserbase.com/v1/projects", { headers }).then((r) => r.json());
  const usage = await fetch(
    `https://api.browserbase.com/v1/projects/${process.env.BROWSERBASE_PROJECT_ID}/usage`,
    { headers }
  ).then((r) => r.json());
  return { projects, usage };
}

```

--------------------------------

### Run TypeScript Scripts

Source: https://github.com/browserbase/playbook/blob/main/node/README.md

Execute TypeScript scripts using tsx. Ensure tsx is installed globally or as a dev dependency.

```bash
npx tsx script.ts
```

--------------------------------

### Get Session Debug URL

Source: https://context7.com/browserbase/playbook/llms.txt

Use this command to retrieve a URL for debugging a specific Browserbase session. Ensure the SESSION_ID and BROWSERBASE_API_KEY environment variables are set.

```bash
curl https://api.browserbase.com/v1/sessions/{SESSION_ID}/debug \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY"
```

--------------------------------

### Get Live Debugger URL for a Session

Source: https://context7.com/browserbase/playbook/llms.txt

Returns a URL for the Browserbase DevTools live view, accessible while the session is active. Requires a session ID.

```typescript
import Browserbase from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function getLiveDebugURL(sessionId: string) {
  const res = await fetch(
    `https://api.browserbase.com/v1/sessions/${sessionId}/debug`,
    { headers: { "X-BB-API-Key": process.env.BROWSERBASE_API_KEY! } }
  );
  const json = await res.json();
  console.log("Debugger URL:", json.debuggerUrl);
  return json.debuggerUrl;
}

// Usage:
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
});
await getLiveDebugURL(session.id);

```

--------------------------------

### Get Session Debug URL

Source: https://context7.com/browserbase/playbook/llms.txt

Retrieves a debug URL for a specific session, allowing for direct inspection of the browser state.

```APIDOC
## GET /v1/sessions/{SESSION_ID}/debug

### Description
Retrieves a debug URL for a specific session.

### Method
GET

### Endpoint
/v1/sessions/{SESSION_ID}/debug

### Parameters
#### Path Parameters
- **SESSION_ID** (string) - Required - The ID of the session to retrieve the debug URL for.
```

--------------------------------

### Extract Structured Data with Zod Schema using `page.extract()` (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Uses an LLM to parse page content into a typed object defined by a Zod schema. This example demonstrates filling a flight search form and extracting flight details.

```typescript
import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

async function main() {
  const stagehand = new Stagehand({ env: "BROWSERBASE" });
  await stagehand.init();
  const page = stagehand.page;

  await page.goto("https://www.alaskaair.com/");

  // Fill flight search
  await page.act({ action: "type in starting location/origin: SFO" });
  await page.act({ action: "select SFO from the origin options" });
  await page.act({ action: "type in destination: LAX" });
  await page.act({ action: "select LAX from the destination options" });
  await page.act({ action: "select 02/01/2025 from the departure date options" });
  await page.act({ action: "select 02/08/2025 from the return date options" });
  await page.act({ action: "click search for flights" });

  // Extract structured data
  const flightData = await page.extract({
    instruction: "extract all flight data: flight number, departure and arrival times, and price",
    schema: z.object({
      flights: z.array(
        z.object({
          flight_number: z.string(),
          departure_time: z.string(),
          arrival_time: z.string(),
          price: z.string(),
        })
      ),
    }),
  });

  console.log(flightData);
  // Output: { flights: [{ flight_number: 'AS123', departure_time: '8:00 AM', arrival_time: '9:35 AM', price: '$79' }, ...] }
  await stagehand.close();
}

main().catch(console.error);
```

--------------------------------

### Upload Local File to Remote Browser (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Injects a local file into a file input element within the cloud browser using Playwright's `setInputFiles` method. Ensure the Browserbase SDK is installed and API key is configured.

```typescript
import { chromium } from "playwright-core";
import Browserbase from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

(async () => {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];

  await page.goto("https://browser-tests-alpha.vercel.app/api/upload-test");

  // Inject the local file into the file input
  await page.locator("#fileUpload").setInputFiles("./files/screenshot.jpeg");

  await browser.close();
})().catch(console.error);

```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/browserbase/playbook/blob/main/node/README.md

Navigate to the playbook's Node.js directory after cloning the repository.

```bash
cd playbook/node
```

--------------------------------

### Configure Browserbase Credentials

Source: https://github.com/browserbase/playbook/blob/main/node/README.md

Set up your Browserbase API Key and Project ID in the .env file.

```dotenv
BROWSERBASE_PROJECT_ID=
BROWSERBASE_API_KEY=
```

--------------------------------

### Create Context and Attach to Session (Python)

Source: https://context7.com/browserbase/playbook/llms.txt

Demonstrates creating a persistent context and then attaching two sessions to it. The first session logs in, and the second reuses the saved cookies from the persistent context.

```python
import os, time
from browserbase import Browserbase
from playwright.sync_api import sync_playwright

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

context_id = bb.contexts.create(project_id=os.environ["BROWSERBASE_PROJECT_ID"])
print("Context ID:", context_id.id)

def make_session(persist: bool):
    return bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        browser_settings={"context": {"id": context_id.id, "persist": persist}},
        keep_alive=True,
        proxies=True,
    )

with sync_playwright() as p:
    # First session: log in
    s1 = make_session(persist=True)
    b1 = p.chromium.connect_over_cdp(s1.connect_url)
    page1 = b1.contexts[0].pages[0]
    page1.goto("https://en.wikipedia.org/w/index.php")
    # ... perform login ...
    b1.close()

    time.sleep(10)  # wait for context to be saved

    # Second session: reuse saved cookies
    s2 = make_session(persist=False)
    b2 = p.chromium.connect_over_cdp(s2.connect_url)
    page2 = b2.contexts[0].pages[0]
    page2.goto("https://en.wikipedia.org/w/index.php")
    b2.close()
```

--------------------------------

### Create a Stealth Session (Python)

Source: https://context7.com/browserbase/playbook/llms.txt

Use this to create a session with advanced stealth features enabled. Requires Scale plan. Ensure `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` environment variables are set.

```python
import os
from browserbase import Browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def create_stealth_session():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        proxies=True,
        browser_settings={
            "advanced_stealth": True,  # Scale plan only
            "fingerprint": {
                "browsers": ["chrome", "firefox"],
                "devices": ["desktop"],
                "locales": ["en-US"],
                "operating_systems": ["macos", "windows"],
                "screen": {"max_width": 1920, "max_height": 1080,
                            "min_width": 1024, "min_height": 768},
            },
            "viewport": {"width": 1920, "height": 1080},
            "solve_captchas": True,
        },
    )
    return session
```

--------------------------------

### Create a Browserbase Session (curl)

Source: https://context7.com/browserbase/playbook/llms.txt

Creates a new browser session using the Browserbase REST API. Requires the project ID and API key.

```bash
curl -X POST https://api.browserbase.com/v1/sessions \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "'
```

--------------------------------

### Create a session

Source: https://context7.com/browserbase/playbook/llms.txt

Creates a new browser session within a specified project.

```APIDOC
## Create a session

### Description
Creates a new browser session.

### Method
POST

### Endpoint
`/v1/sessions`

### Parameters
#### Request Body
- **projectId** (string) - Required - The ID of the project to create the session in.

### Request Example
```bash
curl -X POST https://api.browserbase.com/v1/sessions \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "'
```

--------------------------------

### Create a basic session (Python)

Source: https://context7.com/browserbase/playbook/llms.txt

Creates a new remote browser session using the Browserbase Python SDK. Returns a session object with an ID and connect URL. Requires Playwright for Python to connect to the session.

```python
import os
from browserbase import Browserbase
from playwright.sync_api import sync_playwright

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def create_session():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"]
    )
    print(f"View session at: https://browserbase.com/sessions/{session.id}")
    return session

with sync_playwright() as p:
    session = create_session()
    browser = p.chromium.connect_over_cdp(session.connect_url)
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    browser.close()
```

--------------------------------

### Create a basic session (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Creates a new remote browser session using the Browserbase SDK. Returns a session object with an ID and connect URL. Requires Playwright to connect to the session.

```typescript
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSession() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  console.log(`View session at: https://browserbase.com/sessions/${session.id}`);
  return session;
}

(async () => {
  const session = await createSession();
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];
  await page.goto("https://example.com");
  await browser.close();
})();
```

--------------------------------

### Create a stealth session with fingerprinting and proxies (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Creates a remote browser session with randomized fingerprinting (UA, OS, locale, screen) and routes traffic through Browserbase residential proxies. The `advancedStealth` option requires the Scale plan.

```typescript
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createStealthSession() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    proxies: true,
    browserSettings: {
      advancedStealth: true, // Scale plan only
      fingerprint: {
        browsers: ["chrome", "firefox", "edge", "safari"],
        devices: ["desktop", "mobile"],
        locales: ["en-US", "en-GB"],
        operatingSystems: ["android", "ios", "linux", "macos", "windows"],
        screen: { maxWidth: 1920, maxHeight: 1080, minWidth: 1024, minHeight: 768 },
      },
      viewport: { width: 1920, height: 1080 },
      solveCaptchas: true,
    },
    keepAlive: true,
  });
  return session;
}

(async () => {
  const session = await createStealthSession();
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];
  console.log(`View session at https://browserbase.com/sessions/${session.id}`);
  await page.goto("https://browserbase.com/");
  await page.waitForTimeout(2000);
  await browser.close();
})().catch(console.error);
```

--------------------------------

### Download File with Browserbase and Playwright (Python)

Source: https://context7.com/browserbase/playbook/llms.txt

Initiates a file download in the remote browser and retrieves the zipped downloads using the Browserbase API. Requires API key and project ID from environment variables.

```python
import os, requests
from playwright.sync_api import sync_playwright
from dotenv import load_dotenv
load_dotenv()

API_KEY = os.environ["BROWSERBASE_API_KEY"]
PROJECT_ID = os.environ["BROWSERBASE_PROJECT_ID"]

def create_session():
    r = requests.post(
        "https://www.browserbase.com/v1/sessions",
        headers={"x-bb-api-key": API_KEY},
        json={"projectId": PROJECT_ID},
    )
    r.raise_for_status()
    return r.json()["id"]

def get_zipped_downloads(session_id):
    r = requests.get(
        f"https://www.browserbase.com/v1/sessions/{session_id}/downloads",
        headers={"x-bb-api-key": API_KEY},
    )
    r.raise_for_status()
    return r.content

session_id = create_session()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"wss://connect.browserbase.com?apiKey={API_KEY}&sessionId={session_id}"
    )
    cdp = browser.new_browser_cdp_session()
    cdp.send("Browser.setDownloadBehavior",
             {"behavior": "allow", "downloadPath": "downloads", "eventsEnabled": True})
    page = browser.contexts[0].pages[0]
    page.goto("https://browser-tests-alpha.vercel.app/api/download-test")
    page.get_by_role("link", name="Download File").click()
    page.close()
    browser.close()

with open("downloads.zip", "wb") as f:
    f.write(get_zipped_downloads(session_id))
print("Saved to downloads.zip")

```

--------------------------------

### Create Persistent Context

Source: https://context7.com/browserbase/playbook/llms.txt

Create a persistent context for reusing authentication across multiple sessions. This requires your BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID to be set.

```bash
curl -X POST https://api.browserbase.com/v1/contexts \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "'$BROWSERBASE_PROJECT_ID'"}'
```

--------------------------------

### Configure Custom External Proxy (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Routes all traffic through a user-supplied proxy server. Ensure `BROWSERBASE_PROJECT_ID` environment variable is set.

```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    {
      type: "external",
      server: "http://proxy.example.com:8080",
      username: "proxyuser",
      password: "proxypass",
    },
  ],
});
```

--------------------------------

### Retrieve Session Downloads

Source: https://context7.com/browserbase/playbook/llms.txt

Download all files associated with a specific Browserbase session. The output is saved to downloads.zip. Ensure SESSION_ID and BROWSERBASE_API_KEY are configured.

```bash
curl https://api.browserbase.com/v1/sessions/{SESSION_ID}/downloads \
  -H "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --output downloads.zip
```

--------------------------------

### Create Context and Attach to Session (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Persists cookies, localStorage, and credentials across multiple sessions. Requires `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` environment variables to be set.

```typescript
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createContext(): Promise<string> {
  const context = await bb.contexts.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  console.log("Context ID:", context.id);
  return context.id;
}

async function createSession(contextId: string) {
  return bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      context: { id: contextId, persist: true },
    },
  });
}

(async () => {
  const contextId = await createContext();

  // Session 1: log in and persist cookies
  const session1 = await createSession(contextId);
  const browser1 = await chromium.connectOverCDP(session1.connectUrl);
  const page1 = browser1.contexts()[0].pages()[0];
  await page1.goto("https://github.com/login");
  // ... perform login steps ...
  await browser1.close();

  // Session 2: reuse persisted cookies — already logged in
  await new Promise((r) => setTimeout(r, 10000)); // wait for context to persist
  const session2 = await createSession(contextId);
  const browser2 = await chromium.connectOverCDP(session2.connectUrl);
  const page2 = browser2.contexts()[0].pages()[0];
  await page2.goto("https://github.com");
  await browser2.close();
})();
```

--------------------------------

### Take Full-Page Screenshot (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Connects to a Browserbase session, navigates to a specified URL, captures a full-page screenshot, and saves it locally as a JPEG file. Requires fs, Playwright Core, and dotenv.

```typescript
import { writeFileSync } from "fs";
import { chromium } from "playwright-core";
import Browserbase from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

(async () => {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];

  await page.goto("https://en.wikipedia.org/wiki/Main_Page", {
    waitUntil: "domcontentloaded",
  });

  console.log("Taking screenshot...");
  const buf = await page.screenshot({ fullPage: true, timeout: 0 });
  writeFileSync("screenshot.jpeg", buf);

  await page.close();
  await browser.close();
  console.log("Screenshot saved to screenshot.jpeg");
})();
```

--------------------------------

### Configure Geo-located Browserbase Proxy (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Exits through a Browserbase IP in a specific city, state, or country. Ensure `BROWSERBASE_PROJECT_ID` environment variable is set.

```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    {
      type: "browserbase",
      geolocation: { city: "New York", state: "NY", country: "US" },
    },
  ],
});
```

--------------------------------

### Inspect Session

Source: https://context7.com/browserbase/playbook/llms.txt

Retrieves session details, logs, and recording.

```APIDOC
## Get session details, logs, and recording (TypeScript)

### Description
Retrieves the details, logs, and recording for a given session.

### Method
GET

### Endpoint
`/v1/sessions/{sessionId}`
`/v1/sessions/{sessionId}/logs`
`/v1/sessions/{sessionId}/recording`

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to inspect.

### Request Example
```typescript
async function inspectSession(sessionId: string) {
  const headers = { "X-BB-API-Key": process.env.BROWSERBASE_API_KEY! };
  const base = `https://api.browserbase.com/v1/sessions/${sessionId}`;

  const [details, logs, recording] = await Promise.all([
    fetch(base, { headers }).then((r) => r.json()),
    fetch(`${base}/logs`, { headers }).then((r) => r.json()),
    fetch(`${base}/recording`, { headers }).then((r) => r.json()),
  ]);

  console.log("Details:", details);
  console.log("Logs:", logs);
  console.log("Recording:", recording);
}
```

### Response
#### Success Response (200)
- **details** (object) - Contains detailed information about the session.
- **logs** (object) - Contains the logs for the session.
- **recording** (object) - Contains the recording data for the session.
```

--------------------------------

### Download File with Browserbase and Playwright (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Triggers a download in the remote browser and polls the Browserbase API to retrieve the file as a zip archive. Ensure Browserbase API key and project ID are configured in environment variables.

```typescript
import { chromium } from "playwright-core";
import { writeFileSync } from "node:fs";
import dotenv from "dotenv";
dotenv.config();

async function createSession() {
  const res = await fetch("https://api.browserbase.com/v1/sessions", {
    method: "POST",
    headers: {
      "x-bb-api-key": process.env.BROWSERBASE_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ projectId: process.env.BROWSERBASE_PROJECT_ID }),
  });
  return res.json();
}

async function saveDownloadsOnDisk(sessionId: string, timeoutMs: number) {
  return new Promise<void>((resolve, reject) => {
    const timer = setTimeout(() => clearInterval(poller), timeoutMs);
    const poller = setInterval(async () => {
      const res = await fetch(
        `https://api.browserbase.com/v1/sessions/${sessionId}/downloads`,
        { headers: { "x-bb-api-key": process.env.BROWSERBASE_API_KEY! } }
      );
      const buf = await res.arrayBuffer();
      if (buf.byteLength > 0) {
        writeFileSync("downloads.zip", Buffer.from(buf));
        clearInterval(poller);
        clearTimeout(timer);
        resolve();
      }
    }, 2000);
  });
}

(async () => {
  const { id: sessionId } = await createSession();
  const browser = await chromium.connectOverCDP(
    `wss://connect.browserbase.com?apiKey=${process.env.BROWSERBASE_API_KEY}&sessionId=${sessionId}`
  );
  const page = browser.contexts()[0].pages()[0];

  const client = await browser.contexts()[0].newCDPSession(page);
  await client.send("Browser.setDownloadBehavior", {
    behavior: "allow",
    downloadPath: "downloads",
    eventsEnabled: true,
  });

  await page.goto("https://browser-tests-alpha.vercel.app/api/download-test");
  const [download] = await Promise.all([
    page.waitForEvent("download"),
    page.locator("#download").click(),
  ]);
  if (await download.failure()) throw new Error(await download.failure()!);

  await browser.close();
  await saveDownloadsOnDisk(sessionId, 20000);
  console.log("Files saved to downloads.zip");
})().catch(console.error);

```

--------------------------------

### Configure Domain-based Proxy Routing (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Sends traffic for specific domains through different proxies, with Browserbase as the fallback. Ensure `BROWSERBASE_PROJECT_ID` environment variable is set.

```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    {
      type: "external",
      server: "http://proxy1.example.com",
      username: "user",
      password: "pass",
      domainPattern: "wikipedia\.org",
    },
    {
      type: "external",
      server: "http://proxy2.example.com",
      username: "user",
      password: "pass",
      domainPattern: ".*\.gov",
    },
    { type: "browserbase" }, // fallback for all other domains
  ],
});
```

--------------------------------

### Retrieve Session Downloads

Source: https://context7.com/browserbase/playbook/llms.txt

Fetches all files downloaded during a specific session, typically returned as a zip archive.

```APIDOC
## GET /v1/sessions/{SESSION_ID}/downloads

### Description
Retrieves all files downloaded during a specific session.

### Method
GET

### Endpoint
/v1/sessions/{SESSION_ID}/downloads

### Parameters
#### Path Parameters
- **SESSION_ID** (string) - Required - The ID of the session to retrieve downloads from.
```

--------------------------------

### Persist Login with Stagehand and Browserbase Context

Source: https://context7.com/browserbase/playbook/llms.txt

Combines Stagehand with a Browserbase context to carry session cookies across browser sessions, enabling persistent login. Requires manual input to confirm login completion.

```typescript
import { Stagehand } from "@browserbasehq/stagehand";
import { Browserbase } from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function persistLogin(contextId: string) {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    browserbaseSessionCreateParams: {
      projectId: process.env.BROWSERBASE_PROJECT_ID!,
      browserSettings: { context: { id: contextId, persist: true } },
    },
  });
  await stagehand.init();
  await stagehand.page.goto("https://github.com/login");
  console.log("Log in and press Enter to continue...");
  await new Promise<void>((r) => process.stdin.once("data", r));
  await stagehand.close();
  await new Promise((r) => setTimeout(r, 10000));
}

async function usePersistedLogin(contextId: string) {
  const stagehand = new Stagehand({
    env: "BROWSERBASE",
    browserbaseSessionCreateParams: {
      projectId: process.env.BROWSERBASE_PROJECT_ID!,
      browserSettings: { context: { id: contextId, persist: false } },
    },
  });
  await stagehand.init();
  await stagehand.page.goto("https://github.com"); // already logged in
  await stagehand.close();
}

(async () => {
  const context = await bb.contexts.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  await persistLogin(context.id);
  await usePersistedLogin(context.id);
})();

```

--------------------------------

### Create Persistent Context

Source: https://context7.com/browserbase/playbook/llms.txt

Creates a persistent context that can be reused across multiple sessions for maintaining state, such as authentication.

```APIDOC
## POST /v1/contexts

### Description
Creates a persistent context that can be reused across multiple sessions.

### Method
POST

### Endpoint
/v1/contexts

### Parameters
#### Request Body
- **projectId** (string) - Required - The ID of the project to associate with the context.
```

--------------------------------

### List Sessions Filtered by Metadata

Source: https://context7.com/browserbase/playbook/llms.txt

Queries sessions by arbitrary metadata key/value pairs, useful for tracking sessions per customer or workflow. The query string format is specific.

```typescript
import Browserbase from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

const sessions = await bb.sessions.list({
  q: "user_metadata['client']:'enterprise_customer_xyz'",
});
console.log(sessions);
// Output: [{ id: '...', status: 'COMPLETED', userMetadata: { client: 'enterprise_customer_xyz' } }, ...]

```

--------------------------------

### List sessions filtered by metadata

Source: https://context7.com/browserbase/playbook/llms.txt

Queries sessions by arbitrary metadata key/value pairs, useful for tracking sessions per customer or workflow.

```APIDOC
## List sessions filtered by metadata (TypeScript)

### Description
Queries sessions by arbitrary metadata key/value pairs, useful for tracking sessions per customer or workflow.

### Method
GET

### Endpoint
`/v1/sessions`

### Parameters
#### Query Parameters
- **q** (string) - Required - A query string to filter sessions. Example: `"user_metadata['client']:'enterprise_customer_xyz'"`.

### Request Example
```typescript
import Browserbase from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

const sessions = await bb.sessions.list({
  q: "user_metadata['client']:'enterprise_customer_xyz'",
});
console.log(sessions);
// Output: [{ id: '...', status: 'COMPLETED', userMetadata: { client: 'enterprise_customer_xyz' } }, ...]
```

### Response
#### Success Response (200)
- **sessions** (array) - A list of session objects matching the query.
```

--------------------------------

### Scrape Structured Data from a Page (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Uses `page.evaluate` to run DOM queries in the remote browser and return structured data. Ensure Browserbase API key and project ID are set in environment variables.

```typescript
import { chromium } from "playwright-core";
import { Browserbase } from "@browserbasehq/sdk";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function scrapeBooks() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];

  await page.goto("https://books.toscrape.com/");
  await page.waitForLoadState("load");

  const books = await page.evaluate(() => {
    return Array.from(document.querySelectorAll("article.product_pod")).map((el) => ({
      title: el.querySelector("h3 > a")?.getAttribute("title"),
      price: el.querySelector("p.price_color")?.textContent,
      inStock: el.querySelector("p.instock.availability")?.textContent?.trim(),
      link: el.querySelector("h3 > a")?.getAttribute("href"),
    }));
  });

  await browser.close();
  console.log(books);
  // Output: [{ title: 'A Light in the Attic', price: '£51.77', inStock: 'In stock', link: '...' }, ...]
  return books;
}

scrapeBooks().catch(console.error);
```

--------------------------------

### Custom Captcha Selectors (Python)

Source: https://context7.com/browserbase/playbook/llms.txt

Configures custom CSS selectors for CAPTCHA images and input fields for non-standard CAPTCHAs. Requires Playwright sync API.

```python
import os
from browserbase import Browserbase
from playwright.sync_api import sync_playwright

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

with sync_playwright() as p:
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        browser_settings={
            "captchaImageSelector": "#c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage",
            "captchaInputSelector": "#ctl00_MainContent_txtTuringText",
        },
    )
    browser = p.chromium.connect_over_cdp(session.connect_url)
    page = browser.contexts[0].pages[0]
    page.goto("https://nmlsconsumeraccess.org/")
    page.wait_for_load_state("networkidle")
    page.locator('input[type="text"]').first.fill("alt platform")
    page.click('input[id="searchButton"]')
    page.click("#ctl00_MainContent_cbxAgreeToTerms")
    page.wait_for_timeout(5000)
    page.click("#ctl00_MainContent_btnContinue")
    browser.close()
```

--------------------------------

### High-Security Session (Python)

Source: https://context7.com/browserbase/playbook/llms.txt

Disables session recording and logging for sensitive workflows. Ensure `BROWSERBASE_PROJECT_ID` environment variable is set.

```python
session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    browser_settings={
        "record_session": False,
        "log_session": False,
    },
)
```

--------------------------------

### Attach custom metadata to a session

Source: https://context7.com/browserbase/playbook/llms.txt

Stores arbitrary key/value data on a session for later querying and filtering.

```APIDOC
## Attach custom metadata to a session (TypeScript)

### Description
Stores arbitrary key/value data on a session for later querying and filtering.

### Method
POST

### Endpoint
`/v1/sessions`

### Parameters
#### Request Body
- **projectId** (string) - Required - The ID of the project.
- **userMetadata** (object) - Optional - Arbitrary key/value data to attach to the session.
  - **client** (string) - Example: `"enterprise_customer_xyz"`
  - **workflow** (string) - Example: `"invoice_processing"`
  - **config** (object) - Example: `{ retries: 3, priority: "high" }`

### Request Example
```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  userMetadata: {
    client: "enterprise_customer_xyz",
    workflow: "invoice_processing",
    config: { retries: 3, priority: "high" },
  },
});
// Later: query with bb.sessions.list({ q: "user_metadata['client']:'enterprise_customer_xyz'" })
```

### Response
#### Success Response (200)
- **session** (object) - The created session object with attached metadata.
```

--------------------------------

### Custom Captcha Selectors (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Provides CSS selectors for CAPTCHA images and input fields for non-standard, image-based CAPTCHAs. Requires Playwright Core and dotenv.

```typescript
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
import dotenv from "dotenv";
dotenv.config();

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

(async () => {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      // @ts-ignore
      captchaImageSelector: "#c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage",
      captchaInputSelector: "#ctl00_MainContent_txtTuringText",
    },
  });

  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];
  console.log(`View session at https://browserbase.com/sessions/${session.id}`);

  await page.goto("https://nmlsconsumeraccess.org/");
  await page.waitForLoadState("networkidle");
  await page.locator('input[type="text"]').first().fill("alt platform");
  await page.click('input[id="searchButton"]');
  await page.click("#ctl00_MainContent_cbxAgreeToTerms");

  console.log("Captcha auto-solving...");
  await page.waitForTimeout(5000);

  await page.click("#ctl00_MainContent_btnContinue");
  await page.waitForLoadState("networkidle");
  await browser.close();
})();
```

--------------------------------

### Attach Custom Metadata to a Session

Source: https://context7.com/browserbase/playbook/llms.txt

Stores arbitrary key/value data on a session for later querying and filtering. Metadata can include nested objects and is defined during session creation.

```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  userMetadata: {
    client: "enterprise_customer_xyz",
    workflow: "invoice_processing",
    config: { retries: 3, priority: "high" },
  },
});
// Later: query with bb.sessions.list({ q: "user_metadata['client']:'enterprise_customer_xyz'" })

```

--------------------------------

### Disable Session Recording and Logs (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Prevents Browserbase from storing recordings or logs, suitable for sensitive workflows. Ensure `BROWSERBASE_PROJECT_ID` environment variable is set.

```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: {
    recordSession: false,
    logSession: false,
  },
});
```

--------------------------------

### Automatic Captcha Solving (TypeScript)

Source: https://context7.com/browserbase/playbook/llms.txt

Enables automatic solving of most standard CAPTCHAs by setting `solveCaptchas: true` in browser settings.

```typescript
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  browserSettings: { solveCaptchas: true },
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.