Ruby SDK

goto(url) #

Navigate the browser to a new URL.

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'")

observe #

Read the page content and discover interactive elements. Use scope to limit to a CSS container. Switch to HTML format when you need tag/class names. Use mode: "full" to get content from all page sections (nav, aside, footer, etc.) organized by region. The first observe auto-includes a section map showing available page regions.

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

# Page map is auto-included on first observe
result.page.map.each do |entry|
  puts "#{entry.section}: #{entry.hint}"
end

# Re-request the map on subsequent calls
session.observe(include_page_map: true)

# Get content from all page sections
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 · ...

click #

Click an element. Target by ref (from observe), visible text, or label.

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

fill #

Set the value of an input field. Target by ref, text, or label. Clears existing content first.

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

fill_form #

Fill multiple form fields in a single step. Optionally submit the form.

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

extract #

Extract structured data from the page. Define a schema using Ruby keyword arguments.

# Mix CSS, JS, and AI selectors in a single extraction
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 selector
  }]
)

result.extraction["products"].each do |product|
  puts "#{product['name']}: #{product['price']} (#{product['rating']})"
end

Three selector types work together in the same schema:

• CSS — "h2 >> text", "a >> href", ".price >> text"
• AI — "ai >> the star rating" — resolves to a CSS selector via AI, cached after first call
• JS — "js >> expression" — runs JavaScript against each matched element

screenshot #

Capture a screenshot. The image is returned as base64 in media.

result = session.screenshot(full_page: true)

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

scroll_collect #

Scroll through the page and collect all content. Useful for infinite-scroll pages.

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

close #

Close the browser session and release resources.

session.close

type #

Type text character by character. Useful for inputs with autocomplete or client-side filtering. Target by ref, text, or label.

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

select #

Select a dropdown option by value. Target the select element by ref, text, or label.

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

check #

Toggle a checkbox or radio button. Target by ref, text, or label.

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

scroll #

Scroll the page or scroll an element into view. Target by ref, text, or label.

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

wait #

Wait for a duration, CSS selector, visible text, or a JavaScript expression to become truthy.

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

upload #

Upload files to a file input. Target by ref, text, or label.

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

pdf #

Generate a PDF of the page. Supports format, landscape, background, scale, and margin options.

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))

execute_js #

Run JavaScript code in the browser. The result is stored in the extraction under the specified key.

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)