Ruby SDK

Installation #

Install the gem from RubyGems:

gem install browserbeam

Or add it to your Gemfile:

gem "browserbeam"

Then run:

bundle install

Quick Start #

Create a client, open a session, and interact with a page:

require "browserbeam"

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

session = client.sessions.create(url: "https://example.com")
session.click(text: "More information")
result = session.extract(title: "string", paragraphs: ["string"])
puts result.extraction
session.close

Configuration #

Pass options when you create the client:

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

Creating Sessions #

Call client.sessions.create to launch a browser session. It returns a Session object you use for all subsequent actions.

session = client.sessions.create(
  url: "https://example.com",
  viewport: { width: 1280, height: 720 },
  locale: "en-US",
  timezone: "America/New_York",
  user_agent: "MyBot/1.0",
  proxy: "http://user:pass@proxy.example.com:8080",
  block_resources: ["image", "font"],
  auto_dismiss_blockers: true,
  cookies: [{ name: "session", value: "abc123", domain: ".example.com" }],
  idempotency_key: "unique-request-id"
)

puts session.page.title

Session Methods #

Every method below sends a step to the browser and returns the updated session envelope.

session.goto("https://example.com/about")

# Wait for a CSS selector or JS expression
session.goto("https://example.com", wait_for: ".loaded", wait_timeout: 5000)
session.goto("https://example.com", wait_until: "document.readyState === 'complete'")

result = session.observe(scope: "main", format: "markdown")
puts result.page.markdown.content

result.page.interactive_elements.each do |el|
  puts "#{el.ref} — #{el.tag} — #{el.label}"
end

# By ref from observe results
session.click(ref: "a7")

# By visible text
session.click(text: "Sign in")

# By label (for buttons, links, inputs)
session.click(label: "Submit")

# By ref
session.fill("hello@example.com", ref: "input3")

# By label
session.fill("hello@example.com", label: "Email")

# By visible text
session.fill("hello@example.com", text: "Email")

session.fill_form([
  { label: "Email", value: "hello@example.com" },
  { label: "Password", value: "s3cret" }
], submit: true)

result = session.extract(
  title: "string",
  price: "number",
  features: ["string"]
)

puts result.extraction
# => { "title" => "Pro Plan", "price" => 29, "features" => ["API access", "Priority support"] }

result = session.screenshot(full_page: true)

# Save to file
require "base64"
File.write("page.png", Base64.decode64(result.media.first.data))

result = session.scroll_collect(max_scrolls: 10)
puts result.page.markdown.content

session.close

session.type("search query", ref: "input5", delay: 50)
session.type("hello", label: "Search")

session.select("us", label: "Country")

session.check(label: "I agree to the terms")
session.check(ref: "cb3", checked: false)

session.scroll(to: "bottom")
session.scroll(direction: "down", amount: 500)
session.scroll(text: "Footer section")

session.wait(ms: 2000)
session.wait(selector: ".loaded", timeout: 10000)
session.wait(until: "document.querySelectorAll('.item').length > 5")

session.upload(["https://example.com/file.pdf"], ref: "file1")
session.upload(["https://example.com/photo.jpg"], label: "Upload photo")

result = session.pdf(format: "A4", landscape: true, scale: 0.8,
  margin: { top: "1cm", bottom: "1cm" })
require "base64"
File.write("page.pdf", Base64.decode64(result.media.first.data))

result = session.execute_js("return document.title")
puts result.extraction["js_result"]

# With custom result key and timeout
result = session.execute_js("return document.querySelectorAll('a').length",
  result_key: "link_count", timeout: 5000)

Session Management #

List, inspect, and destroy sessions through the client.sessions namespace.

List sessions

result = client.sessions.list(status: "active", limit: 10)
result.sessions.each do |s|
  puts "#{s.session_id} — #{s.status} — #{s.started_at}"
end

# Pagination
if result.has_more
  next_page = client.sessions.list(after: result.next_cursor)
end

Get session info

info = client.sessions.get("ses_abc123")
puts info.status        # => "active"
puts info.expires_at    # => "2026-03-24T12:00:00Z"

Destroy a session

client.sessions.destroy("ses_abc123")

Error Handling #

All errors inherit from Browserbeam::Error. Each error exposes message, code, status_code, context, and request_id.

begin
  session = client.sessions.create(url: "https://example.com")
  session.click(ref: "missing")
  session.close
rescue Browserbeam::RateLimitError => e
  puts "Rate limited. Retry after #{e.retry_after}s"
rescue Browserbeam::SessionNotFoundError => e
  puts "Session gone: #{e.message}"
rescue Browserbeam::AuthenticationError => e
  puts "Bad API key: #{e.message}"
rescue Browserbeam::Error => e
  puts "Error [#{e.code}]: #{e.message}"
  puts "Request ID: #{e.request_id}"
end

Full Example #

Extract the top stories from Hacker News, search for a topic, and save a screenshot.

require "browserbeam"
require "base64"
require "json"

client = Browserbeam::Client.new

# Navigate to Hacker News
session = client.sessions.create(url: "https://news.ycombinator.com/")

# Extract top stories from the front page
result = session.extract(
  stories: [{ "_parent": ".titleline", "title": "a >> text", "url": "a >> href" }]
)
result.extraction["stories"].first(5).each do |story|
  puts "#{story['title']} — #{story['url']}"
end

# Fill the search form and submit
session.fill_form({ "q" => "browser automation" }, submit: true)

# Take a screenshot of search results
shot = session.screenshot(full_page: true)
File.write("hn-search.png", Base64.decode64(shot.media.first.data))

session.close