Browserbeam Python SDK

Official Python SDK for the Browserbeam API — browser automation built for AI agents.

Installation

pip install browserbeam

Quick Start

from browserbeam import Browserbeam

client = Browserbeam(api_key="sk_live_...")

session = client.sessions.create(url="https://example.com")

# Page state is available immediately
print(session.page.title)
print(session.page.interactive_elements)

# Interact with the page
session.click(ref="e1")

# Extract with CSS, AI, and JS selectors combined
result = session.extract(
    products=[{
        "_parent": ".product-card",
        "_limit": 3,
        "name": "h2 >> text",                          # CSS selector
        "price": ".price >> text",                     # CSS selector
        "url": "a >> href",                            # CSS attribute
        "rating": "ai >> the star rating out of 5",    # AI selector
        "in_stock": "js >> el.querySelector('.stock')?.textContent.includes('In stock')",  # JS
    }]
)
print(result.extraction)

# Close when done
session.close()

Async Support

from browserbeam import AsyncBrowserbeam

client = AsyncBrowserbeam(api_key="sk_live_...")

session = await client.sessions.create(url="https://example.com")
await session.click(ref="e1")
result = await session.extract(title="h1 >> text")
print(result.extraction)
await session.close()

Configuration

client = Browserbeam(
    api_key="sk_live_...",       # or set BROWSERBEAM_API_KEY env var
    base_url="https://api.browserbeam.com",  # default
    timeout=120.0,               # request timeout in seconds
)

Session Options

session = client.sessions.create(
    url="https://example.com",
    viewport={"width": 1280, "height": 720},
    user_agent="Mozilla/5.0 ...",  # omit for automatic rotation
    locale="en-US",
    timezone="America/New_York",
    block_resources=["image", "font"],
    auto_dismiss_blockers=True,
    timeout=300,
)

Proxies

All sessions use a datacenter proxy by default (country auto-detected from the URL's TLD). No configuration needed. To customize:

# Use a residential proxy for a specific country
session = client.sessions.create(
    url="https://example.com",
    proxy={"kind": "residential", "country": "us"},
)

# Or bring your own proxy (overrides managed proxy)
session = client.sessions.create(
    url="https://example.com",
    proxy="http://user:pass@proxy:8080",
)

Available Methods

Page Map & Full Mode

The first observe call automatically includes a page.map — a lightweight structural outline of the page's landmark regions (header, nav, main, aside, footer) with CSS selectors and descriptive hints. Use it to discover what content is available outside the main area.

res = session.observe()
for entry in res.page.map:
    print(f"{entry.section}: {entry.hint}")
# nav: Home · Docs · Pricing
# main: Getting started with Browserbeam...
# aside: Related posts · Popular tags

To re-request the map on subsequent calls:

session.observe(include_page_map=True)

When you need content from all page sections (sidebars, footer links, nav items), use mode="full". The response markdown is organized by region headers:

full = session.observe(mode="full", max_text_length=20_000)
print(full.page.markdown.content)
# ## [nav]
# Home · Docs · Pricing
# ## [main]
# ...article content...
# ## [aside]
# Related posts · ...

Both parameters work identically with AsyncSession.

Session Management

Filter by status: "active", "closed", or "failed". Failed sessions ended with a fatal error; get returns error_code and error_message.

sessions = client.sessions.list(status="active")
failed = client.sessions.list(status="failed")

info = client.sessions.get("ses_abc123")
if info.status == "failed":
    print(info.error_code, info.error_message)

client.sessions.destroy("ses_abc123")

Error Handling

from browserbeam import Browserbeam, RateLimitError, SessionNotFoundError

client = Browserbeam()

try:
    session = client.sessions.create(url="https://example.com")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except SessionNotFoundError as e:
    print(f"Session not found: {e.message}")

Documentation

Full API documentation at browserbeam.com/docs.

License

MIT