Python SDK

pip install browserbase

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 = 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",
    },
)

# 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",
        },
    ],
)

# 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",
    },
)

agent = bb.agents.create(
    name="Job Finder",
    system_prompt="Find the best matching role on the company's official job board.",
    result_schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
        },
        "required": ["title", "url"],
    },
)

run = bb.agents.runs.create(
    agent_id=agent.agent_id,
    task="Find the best backend engineering role for %candidate%",
    variables={
        "candidate": {
            "value": "a distributed-systems engineer",
            "description": "The candidate profile to match against open roles",
        },
    },
    result_schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
        },
        "required": ["title", "url"],
    },
    browser_settings={
        "proxies": True,
        "verified": True,
        "context": {
            "id": "context-id",
            "persist": True,
        },
    },
)

print(run.run_id, run.status)