Browserbeam Ruby SDK

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

Installation

gem install browserbeam

Or add to your Gemfile:

gem "browserbeam"

Quick Start

require "browserbeam"

client = Browserbeam::Client.new(api_key: "sk_live_...")

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

# Page state is available immediately
puts session.page.title
puts 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
  }]
)
puts result.extraction

# Close when done
session.close

Configuration

client = Browserbeam::Client.new(
  api_key: "sk_live_...",       # or set BROWSERBEAM_API_KEY env var
  base_url: "https://api.browserbeam.com",  # default
  timeout: 120,                 # 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

Method	Description
session.goto(url)	Navigate to a URL
session.observe	Get page state as markdown. Supports mode: "full" for all sections.
session.click(ref:)	Click an element by ref, text, or label
session.fill(value, ref:)	Fill an input field
session.type(value, label:)	Type text character by character
session.select(value, label:)	Select a dropdown option
session.check(label:)	Toggle a checkbox
session.scroll(to: "bottom")	Scroll the page
session.scroll_collect	Scroll and collect all content
session.screenshot	Take a screenshot
session.extract(**schema)	Extract structured data
session.fill_form(fields, submit:)	Fill and submit a form
session.wait(ms:)	Wait for time, selector, or text
session.pdf	Generate a PDF
session.execute_js(code)	Run JavaScript
session.close	Close the session

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
res.page.map.each { |entry| puts "#{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)
puts full.page.markdown.content
# ## [nav]
# Home · Docs · Pricing
# ## [main]
# ...article content...
# ## [aside]
# Related posts · ...

Session Management

sessions = client.sessions.list(status: "active")
info = client.sessions.get("ses_abc123")
client.sessions.destroy("ses_abc123")

Error Handling

begin
  session = client.sessions.create(url: "https://example.com")
rescue Browserbeam::RateLimitError => e
  puts "Rate limited. Retry after #{e.retry_after}s"
rescue Browserbeam::SessionNotFoundError => e
  puts "Session not found: #{e.message}"
end

Documentation

Full API documentation at browserbeam.com/docs.

License

MIT