scrapio

Official Ruby SDK for Scrapio — fetch, crawl, search, and extract structured data from any URL.

Install

gem install scrapio

Or add to your Gemfile:

gem "scrapio"

Requires Ruby 2.7 or later.

Quickstart

require "scrapio"

client = Scrapio::Client.new(ENV["SCRAPIO_API_KEY"])

result = client.fetch.fetch(url: "https://example.com", output: ["markdown"])
puts result["outputs"]["markdown"]

Usage

Fetch a page

result = client.fetch.fetch(
  url:       "https://news.ycombinator.com",
  render_js: true,
  output:    ["markdown"]
)

results = client.google.search(
  search:       "best web scraping API 2025",
  country_code: "us"
)
puts results["results"]

Amazon product

product = client.amazon.get_product("B08N5WRWNW")
puts "#{product["title"]} — $#{product["price"]}"

items = client.walmart.search("headphones")

YouTube video

video = client.youtube.get_video("dQw4w9WgXcQ")

Browser automation

result = client.interact.interact(
  url:     "https://example.com",
  actions: [
    { type: "click", selector: "#login" },
    { type: "type",  selector: "#email", value: "user@example.com" },
  ]
)

Crawl a site

result = client.crawl.crawl(
  seeds:     ["https://docs.example.com"],
  max_pages: 50,
  output:    ["markdown"]
)
puts result["result"]["summary"]["pages_succeeded"]

Async jobs

job = client.jobs.create(
  job_type: "fetch",
  payload:  { url: "https://example.com", output: ["markdown"] }
)

result = client.jobs.wait_for_completion(job["job_id"])

Configuration

client = Scrapio::Client.new(
  ENV["SCRAPIO_API_KEY"],
  base_url: "https://api.scrapio.dev",  # optional override
  timeout:  30                           # optional, default 30s
)

Error handling

begin
  result = client.fetch.fetch(url: "https://example.com")
rescue Scrapio::AuthError
  puts "Invalid API key"
rescue Scrapio::CreditsExhaustedError
  puts "No credits remaining"
rescue Scrapio::RateLimitError
  puts "Rate limited — back off and retry"
rescue Scrapio::ScrapioError => e
  puts "API error #{e.status_code}: #{e.message}"
end

License

MIT