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 structured data
result = session.extract(
  title: "h1 >> text",
  links: ["a >> href"]
)
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 },
  locale: "en-US",
  timezone: "America/New_York",
  proxy: "http://user:pass@proxy:8080",
  block_resources: ["image", "font"],
  auto_dismiss_blockers: true,
  timeout: 300,
)

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

browserbeam

Runtime