Skip to main content
If you’re working with Python, the official browserbase package is the easiest way to connect to and control headless browsers running on Browserbase.

​
Installation

pip install browserbase

​
Basic usage

Here’s an example using the Browserbase Python SDK to create and connect to a session with Playwright: 
from playwright.sync_api import sync_playwright
from browserbase import Browserbase
import os

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

# Create a session on Browserbase
session = bb.sessions.create()

# Connect to the remote session
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(session.connect_url)
context = browser.contexts[0]
page = context.pages[0]

page.goto("https://news.ycombinator.com/")
page.close()
browser.close()
playwright.stop()

print(f"Session complete! View recording at https://browserbase.com/sessions/{session.id}")

​
Session configuration

Pass configuration options when creating a session to customize browser behavior.

​
All configuration options

session = bb.sessions.create(
    # Project ID (optional - inferred from API key if not provided)
    project_id="your-project-id",

    # Proxy configuration
    proxies=True,  # Use default proxy

    # Region where the session runs
    region="us-west-2",

    # Keep session alive after disconnection
    keep_alive=True,

    # Session timeout in seconds (60-21600)
    timeout=3600,

    # Extension ID (uploaded via Upload Extension API)
    extension_id="ext_abc123",

    # Browser settings
    browser_settings={
        # Toggle features
        "blockAds": True,
        "solveCaptchas": True,
        "recordSession": True,
        "logSession": True,
        "verified": True,

        # Operating system (only available with verified)
        # Controls user agent and environment signals
        "os": "windows",

        # Context for session persistence
        "context": {
            "id": "my-context-id",
            "persist": True,
        },

        # Viewport configuration (ignored when verified is enabled)
        "viewport": {
            "width": 1920,
            "height": 1080,
        },

        # Custom CAPTCHA selectors
        "captchaImageSelector": "#captcha-image",
        "captchaInputSelector": "#captcha-input",
    },

    # Custom metadata for the session
    user_metadata={
        "userId": "user_123",
        "taskName": "data-extraction-job",
    },
)

​
Proxy configuration

Configure proxies as a boolean or a list for more control: 
# Using Browserbase managed proxy with geolocation
session = bb.sessions.create(
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {
                "country": "US",
                "state": "CA",
                "city": "San Francisco",
            },
        },
    ],
)

# Using external proxy
session = bb.sessions.create(
    proxies=[
        {
            "type": "external",
            "server": "http://proxy.example.com:8080",
            "username": "user",
            "password": "pass",
            "domainPattern": "*.example.com",
        },
    ],
)

# Multiple proxies with domain patterns
session = bb.sessions.create(
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {"country": "US"},
            "domainPattern": "*.google.com",
        },
        {
            "type": "external",
            "server": "http://proxy.example.com:8080",
            "domainPattern": "*.example.com",
        },
    ],
)

​
Common configuration examples

# Verified with proxy
session = bb.sessions.create(
    proxies=True,
    browser_settings={
        "verified": True,
        "os": "windows",
    },
)

# Long-running session with keep-alive
session = bb.sessions.create(
    timeout=21600,  # 6 hours
    keep_alive=True,
)

# Session with context persistence
session = bb.sessions.create(
    browser_settings={
        "context": {
            "id": "user-session-context",
            "persist": True,
        },
    },
)

# Custom viewport and ad blocking
session = bb.sessions.create(
    browser_settings={
        "viewport": {"width": 1440, "height": 900},
        "blockAds": True,
    },
)

# Mobile viewport
session = bb.sessions.create(
    browser_settings={
        "viewport": {"width": 390, "height": 844},
    },
)

# Session in specific region with metadata
session = bb.sessions.create(
    region="eu-central-1",
    user_metadata={
        "jobId": "job_456",
        "environment": "production",
    },
)

Examples

Quickstart examples using CAPTCHA solving, proxies, extensions, and more.

PyPI package

View the package on PyPI

SDK reference

View the complete SDK reference documentation