ScrapeUnblocker Documentation

The official Node.js / TypeScript client wraps the ScrapeUnblocker API in a small, fully typed package - typed errors, automatic retries, ESM + CommonJS, zero runtime dependencies.

npm install scrapeunblocker

Requires Node.js 18+.

Prefer no dependencies? The API is plain HTTP, so you can skip the package and use Node’s built-in fetch directly - see Raw HTTP at the bottom.

Store your API key in an environment variable so the client picks it up automatically:

export SCRAPEUNBLOCKER_KEY="YOUR_API_KEY"

Quickstart

import { ScrapeUnblockerClient } from "scrapeunblocker";

const su = new ScrapeUnblockerClient(); // reads SCRAPEUNBLOCKER_KEY, or { apiKey: "YOUR_API_KEY" }

const html = await su.getPageSource("https://example.com");

CommonJS works too: const { ScrapeUnblockerClient } = require("scrapeunblocker");

Get Markdown for LLMs

getMarkdown() (0.13.0+) returns the page as clean Markdown for LLMs, agents and RAG pipelines: headings, lists, tables, absolute links and images with alt text, without scripts, styles, navigation or footer. By default you get the main content only. It takes the same options as getPageSource() except listElements, and is billed the same.

const md = await su.getMarkdown("https://en.wikipedia.org/wiki/Web_scraping");

// The whole page, not only the main content
const full = await su.getMarkdown(url, { mainContentOnly: false });

See Markdown for LLMs for what is kept and what is dropped.

Get parsed JSON instead of HTML

getParsed() returns structured data extracted using Schema.org, __NEXT_DATA__, or AI-generated rules - no per-site parsers to maintain.

const product = await su.getParsed("https://www.amazon.com/dp/B08N5WRWNW");

console.log(product.pageType); // "product"
console.log(product.data);     // the fields

If a parse ever comes back wrong, force a fresh set of rules:

const fresh = await su.getParsed(url, { refreshRules: true, rulesHint: "price is missing" });

When the page loads but nothing can be extracted from it, getParsed() does not raise: it returns a result with page type unknown and empty data, together with the rendered HTML (the API’s data_extracted: false and html fields). The call is billed like a page-source call. See when nothing can be extracted. See the parsed data guide for response shapes.

Scrape a Google SERP

const serp = await su.serp("best running shoes", { pagesToCheck: 2 });

for (const result of serp.organic) {
  console.log(result.position, result.title, result.url);
}

Force a country

proxyCountry works on every method.

const result = await su.getParsed("https://www.amazon.de/dp/B08N5WRWNW", { proxyCountry: "de" });

Capture cookies and the proxy used

const page = await su.getPageWithCookies("https://example.com");
console.log(page.html, page.cookies, page.proxy);

Fetch an image

import { writeFile } from "node:fs/promises";
const bytes = await su.getImage("https://example.com/photo.jpg");
await writeFile("photo.jpg", bytes);

Drive the browser with steps

Pass a native array of actions to run in a real browser after the page loads. You get back the HTML of the resulting state.

const html = await su.getPageSource("https://example.com", {
  steps: [
    { action: "type", selector: "input[name=q]", value: "wireless headphones" },
    { action: "press_key", value: "Enter" },
    { action: "wait_for", selector: ".search-results", timeout_ms: 10000 },
  ],
});

Discover the selectors first with listElements: true, which makes getPageSource() return the page’s interactive elements as parsed JSON instead of HTML:

const page = await su.getPageSource("https://example.com", { listElements: true });

// The SDK types elements as unknown[]; the fields are listed in the browser steps guide.
for (const el of page.elements as { tag: string; selector: string; text: string }[]) {
  console.log(el.tag, el.selector, el.text);
}

Each element’s selector drops straight into a steps action. Full action reference in the browser steps guide.

Amazon

Product and search data as JSON, priced in the marketplace’s own currency:

// One product by ASIN (or { url: "https://www.amazon.de/dp/B0BSHF7WHW" })
const product = await su.amazonProduct({ asin: "B0BSHF7WHW", marketplace: "amazon.com" });
console.log(product.title, product.price, product.currency, product.rating);

// Keyword search
const results = await su.amazonSearch("wireless headphones", { sort: "price_asc" });
for (const item of results.results) {
  console.log(item.title, item.price, item.currency, item.asin);
}

proxyCountry defaults to the marketplace’s home country (amazon.com -> US, amazon.de -> DE), so prices come back in the right currency with no configuration. Full field list on the Amazon plugin page.

eBay search

Listings from any of the 19 regional eBay marketplaces as JSON:

const items = await su.ebaySearch("iphone 13", {
  marketplace: "ebay.com",
  condition: "used",
  sort: "newly_listed",
});

if (items.exactMatches) {
  for (const item of items.results) {
    console.log(item.title, item.price, item.currency, item.condition);
  }
}

exactMatches is false when eBay found nothing for the keyword and answered with its own loosely-related suggestions instead. Full field list on the eBay Search plugin page.

Skyscanner plugins

Flights, hotels and car hire as JSON:

const locations = await su.skyscanner.flightLocations("London");

const flights = await su.skyscanner.flights({
  origin: "London", dest: "New York",
  depart_date: "2026-09-01", adults: 1, currency: "USD",
});

const hotels = await su.skyscanner.hotels({ destination: "Madrid", checkin: "2026-09-01", checkout: "2026-09-03" });
const cars = await su.skyscanner.carhire({ pickup: "Madrid", pickup_datetime: "2026-09-01T10:00", dropoff_datetime: "2026-09-03T10:00" });

Every other plugin

The SDK has a method for every plugin (0.10.0 and later) - the plugin’s main input goes in as the first argument(s), everything else in one options object (camelCase keys), and options you leave out are not sent, so the API’s defaults apply. Each plugin page shows its method next to cURL. Methods for newer plugins come with newer releases: the Google Hotels, Google News, Google Ads Transparency, Shopee, Taobao, Upwork, Smyths Toys and Wish methods need 0.14.0 or later.

const products = await su.targetSearch("coffee maker", { sort: "price_low", maxResults: 48 });
const milk = await su.woolworthsProduct("888137");                     // one product, with nutrition
const trends = await su.googleTrends(["coffee", "tea"], { geo: "US" }); // a list is sent comma-separated
const reviews = await su.trustpilotReviews("www.nike.com", { stars: [4, 5] });
const hotels = await su.googleHotels("Lisbon", { checkIn: "2026-11-20", checkOut: "2026-11-22" }); // 0.14.0+

// Any plugin endpoint by path, parameters named as the API names them
const data = await su.plugin("/marketplace/target-search", { query: "tv", max_results: 24 });

Concurrency

Every method returns a promise, so cap concurrency with a semaphore for high-throughput crawls:

import { ScrapeUnblockerClient } from "scrapeunblocker";

const su = new ScrapeUnblockerClient();
const CONCURRENCY = 10;

async function scrapeAll(urls: string[]) {
  const results: unknown[] = [];
  const queue = [...urls];
  async function worker() {
    let url;
    while ((url = queue.shift())) results.push(await su.getParsed(url));
  }
  await Promise.all(Array.from({ length: CONCURRENCY }, worker));
  return results;
}

Error handling

Non-2xx responses reject with typed errors, all subclasses of ScrapeUnblockerError. Transient failures (429, 502, 503, 504 and network errors) are retried automatically with exponential backoff; a 401 or 402 is never retried, because it clears when the key or the billing state changes.

import {
  ScrapeUnblockerClient,
  BlockedError,
  PaymentRequiredError,
  RateLimitError,
  UpstreamOutageError,
} from "scrapeunblocker";

const su = new ScrapeUnblockerClient();
try {
  await su.getPageSource("https://example.com");
} catch (err) {
  if (err instanceof BlockedError) {
    // 403: the target blocked every bypass path (not billed)
  } else if (err instanceof PaymentRequiredError) {
    // 402: quota, credit limit, or a failed payment - fix billing
  } else if (err instanceof RateLimitError) {
    // 429: slow down
  } else if (err instanceof UpstreamOutageError) {
    // 503: the target site itself is down - retry later
  }
}

Error	Status	Meaning
`InvalidRequestError`	400	Bad URL, unsupported scheme, or the API key header was not sent
`AuthenticationError`	401	Key not recognised - typo, stray whitespace, or a rotated key
`NoSubscriptionError`	401	Key is fine, but the account has no active plan
`PaymentRequiredError`	402	Billing block - base class for the four below
`QuotaExceededError`	402	The plan’s requests for this period are used up
`CreditLimitExceededError`	402	Unpaid balance is past the account’s credit limit
`BudgetExceededError`	402	This period’s spend reached the monthly budget limit you set in your profile (from SDK 0.9.0)
`PaymentFailedError`	402	A card payment was declined three times
`BlockedError`	403	Blocked by bot protection on every path
`NotFoundError`	404	A plugin lookup found nothing
`TargetNotFoundError`	404 / 410	The target site says the page does not exist (`X-Origin-Status` set). Billed; carries `originStatus`, `html` and `destinationUrl`. Subclass of `NotFoundError`, never retried
`BrowserTimeoutError`	408	Our browser run timed out before the page was ready
`UnsupportedContentError`	415	The URL serves something other than HTML (page methods) or other than an image (`getImage`)
`ValidationError`	422	Missing or wrong-typed parameter; `body` holds the `detail` array
`RateLimitError`	429	Too many requests
`UpstreamOutageError`	503	The target origin is down
`ServerError`	5xx	Unexpected server error, including a 504 upstream timeout
`ScrapeTimeoutError`	-	This client gave up locally before the API answered
`ConnectionError`	-	Could not reach the API

The 402 and 404-422 errors were added in 0.1.6; before that they arrived as a bare APIError. Nothing was removed, so instanceof APIError checks written against earlier versions keep working. See all status codes in Errors.

Tune the retry count and timeout on the client:

new ScrapeUnblockerClient({ timeout: 180000, maxRetries: 2 });

See handling failures for what each status code means.

Raw HTTP (without the package)

The API is plain HTTP, so Node’s built-in fetch (Node 18+) is enough - no SDK required.

const response = await fetch(
  "https://api.scrapeunblocker.com/getPageSource?url=https://example.com&parsed_data=true",
  { method: "POST", headers: { "x-scrapeunblocker-key": process.env.SCRAPEUNBLOCKER_KEY } },
);
const payload = await response.json();
console.log(payload.data.page_type);

The endpoints are getPageSource, serpApi, and getImage; every parameter shown above maps to a query parameter of the same name.

Get Started

No-code area

Spider Cloud

Plugins

AI Assistants

Guides

Code Examples

Node.js

Quickstart

Get Markdown for LLMs

Get parsed JSON instead of HTML

Scrape a Google SERP

Force a country

Capture cookies and the proxy used

Fetch an image

Drive the browser with steps

Amazon

eBay search

Skyscanner plugins

Every other plugin

Concurrency

Error handling

Raw HTTP (without the package)

​Quickstart

​Get Markdown for LLMs

​Get parsed JSON instead of HTML

​Scrape a Google SERP

​Force a country

​Capture cookies and the proxy used

​Fetch an image

​Drive the browser with steps

​Amazon

​eBay search

​Skyscanner plugins

​Every other plugin

​Concurrency

​Error handling

​Raw HTTP (without the package)

Quickstart

Get Markdown for LLMs

Get parsed JSON instead of HTML

Scrape a Google SERP

Force a country

Capture cookies and the proxy used

Fetch an image

Drive the browser with steps

Amazon

eBay search

Skyscanner plugins

Every other plugin

Concurrency

Error handling

Raw HTTP (without the package)