@scrapio/api

Official TypeScript / Node.js SDK for Scrapio — fetch, crawl, search, and extract structured data from any URL.

Install

npm install @scrapio/api

Requires Node.js 18 or later. Ships with ESM and CJS builds and full TypeScript types.

Quickstart

import { ApiClient } from "@scrapio/api";

const client = new ApiClient({ apiKey: process.env.SCRAPIO_API_KEY! });

const result = await client.fetch.fetch({
  url: "https://example.com",
  output: ["markdown"],
});

console.log(result.outputs.markdown);

Usage

Fetch a page

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

Google Search

const results = await client.google.search({
  search: "best web scraping API 2025",
  country_code: "us",
  search_type: "classic",
});
console.log(results.organic_results);

Fast Search

const results = await client.fastSearch.search({
  search: "best web scraping API 2025",
  country_code: "us",
});
console.log(results.organic_results);

Amazon product

const product = await client.amazon.getProduct({ asin: "B08N5WRWNW" });
console.log(product.title, product.price);

Walmart search

const items = await client.walmart.search({ query: "headphones" });

YouTube transcript

const video = await client.youtube.getVideo({ video_id: "dQw4w9WgXcQ" });

Browser automation

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

Crawl a site

const result = await client.crawl.crawl({
  seeds: ["https://docs.example.com"],
  max_pages: 50,
});

Async jobs

const job = await client.jobs.create({
  kind: "fetch",
  input: { url: "https://example.com", output: ["markdown"] },
});

const result = await client.jobs.waitForCompletion(job.job_id, {
  pollIntervalMs: 2000,
  timeoutMs: 120_000,
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key | | baseUrl | string | https://api.scrapio.dev | Override for local/staging | | timeoutMs | number | 30000 | Per-request timeout | | maxRetries | number | 3 | Max retries on 429/503 |

Error handling

import {
  ApiClient,
  AuthError,
  RateLimitError,
  CreditsExhaustedError,
  ApiError,
} from "@scrapio/api";

try {
  await client.fetch.fetch({ url: "https://example.com" });
} catch (err) {
  if (err instanceof AuthError) {
    console.error("Invalid API key");
  } else if (err instanceof CreditsExhaustedError) {
    console.error("No credits remaining");
  } else if (err instanceof RateLimitError) {
    console.error("Rate limited — back off and retry");
  } else if (err instanceof ApiError) {
    console.error(`API error ${err.statusCode}: ${err.message}`);
  }
}

Links

• Documentation
• API Reference
• Dashboard
• Get an API key

License

MIT