Node.js SDK

The official @mrscraper/sdk package exposes three functions: scraper_api to fetch page content (HTML, Markdown, or screenshots), web_search to retrieve real-time web search results, and account to check your subscription and token usage from your Node.js applications.

Requirements

• Node.js 18 or later
• ES Modules enabled in your package.json

{
  "type": "module"
}

Installation

Install the SDK using npm:

npm install @mrscraper/sdk

Authentication

Set your API token as an environment variable. The SDK reads MRSCRAPER_API_TOKEN automatically. You can get your API token from the MrScraper dashboard.

export MRSCRAPER_API_TOKEN="MRSCRAPER_API_TOKEN"

For more information on generating API tokens, see the Generate Token guide.

Quick Start

import { scraper_api, web_search, account, MrScraperError } from "@mrscraper/sdk";

try {
  // 1. Fetch page content
  const page = await scraper_api("https://example.com");
  console.log(page.status_code, page.data);

  // 2. Search the web
  const search = await web_search("python web scraping", { country: "us" });
  console.log(search.data.data);

  // 3. Check remaining tokens
  const status = await account();
  console.log(status.data.token_remaining);
} catch (err) {
  if (err instanceof MrScraperError) {
    console.error(`[${err.status ?? "network"}] ${err.message}`);
  } else {
    throw err;
  }
}

Response Format

All functions are async and resolve to a MrScraperResponse object:

You can type data with a generic parameter:

const result = await scraper_api<string>("https://example.com");

Core Methods

Scraper API

Use scraper_api to fetch a page through the MrScraper Scraper API. The service handles JavaScript rendering, bot detection, and optional geolocation proxying.

import { writeFile } from "node:fs/promises";
import { scraper_api } from "@mrscraper/sdk";

// HTML only (the default) returns the page as a string
const page = await scraper_api("https://example.com");
console.log(page.data);

// Markdown or a screenshot returns an object with one entry per output
const result = await scraper_api("https://example.com", {
  html: true,
  markdown: true,
  screenshot: true,
  geo_code: "US",
  timeout: 120,
  // token: "optional_override_token"
});
if (typeof result.data !== "string") {
  console.log(result.data.markdown);
  if (result.data.screenshot) {
    await writeFile("page.jpg", Buffer.from(result.data.screenshot, "base64"));
  }
}

Requesting only HTML returns the page as a string. Requesting Markdown or a screenshot returns an object such as { html, markdown, screenshot } with an entry for each requested output, typed as ScraperApiData. The screenshot is a base64-encoded JPEG. At least one of html, markdown, or screenshot must be true.

The SDK sends a GET request to https://api.mrscraper.com, with the target URL and every option in the query string.

Parameters:

The first argument is the target URL. All other parameters go in the optional options object.

For more examples of what you can fetch, see Scrape HTML, Scrape Markdown, and Get Screenshot.

Web Search

Use web_search to search the web and retrieve real-time search results, including relevant website URLs, titles, and descriptions. The first argument is the search query.

import { web_search } from "@mrscraper/sdk";

const result = await web_search("python web scraping", {
  country: "us",
  num_results: 10,
  // token: "optional_override_token"
});
for (const item of result.data.data) {
  console.log(item.rank, item.title, item.url);
}

The SDK sends this request:

curl --location 'https://api.mrscraper.com' \
--header 'x-api-token: {MRSCRAPER_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "action": "websearch",
    "query": "python web scraping",
    "country": "us",
    "numResults": 10
}'

Parameters:

Response (result.data, typed as WebSearchResponse):

Account

Use account to check the identity, subscription, token quota, and rate limits of the account that owns the API token.

import { account } from "@mrscraper/sdk";

const result = await account({
  timeout: 30,
  // token: "optional_override_token"
});
console.log(result.data.subscription_status);
console.log(result.data.token_remaining);
console.log(result.data.user.email);

Parameters:

Account summary (result.data, typed as AccountSummary):

TypeScript Types

The package ships its own type definitions:

import type {
  ScraperApiOptions,
  ScraperApiData,
  WebSearchOptions,
  WebSearchResponse,
  WebSearchResult,
  AccountOptions,
  AccountSummary,
  MrScraperResponse,
} from "@mrscraper/sdk";

Error Handling

All functions reject with MrScraperError for API, authentication, network, and timeout failures. Invalid options throw a TypeError or RangeError before any request is sent.

Exception Properties

Example Error Handling

import { scraper_api, MrScraperError } from "@mrscraper/sdk";

try {
  await scraper_api("https://example.com");
} catch (err) {
  if (err instanceof MrScraperError) {
    console.error(`Error: ${err.message}`);
    console.error(`Status: ${err.status ?? "network error"}`);
  } else {
    // Handle unexpected errors
    throw err;
  }
}

Best Practices

• Always wrap SDK calls in try-catch blocks
• Check err instanceof MrScraperError before accessing error properties
• Log errors with appropriate context for debugging
• Implement retry logic for network errors (when status is undefined)
• Verify your API token if you encounter status 401

Migrating from Earlier Versions

From Version 4

Version 5.0.0 returns to three public functions. The 4.x format-specific functions (scraper_html, scraper_markdown, get_screenshot, scraper_json, scraper_multiple_page, scraper_sitemap, scrape_brand, and get_brand) and their option types are no longer exported. Use scraper_api with output flags instead:

A screenshot from scraper_api is a base64-encoded JPEG in data.screenshot, not a Buffer.

From Version 3

• web_search now calls the MrScraper API with action: "websearch" and returns JSON. Its first argument is the search query, and it accepts country and num_results (10 to 100). The raw, format, region, language, page, and render_js options and search URL input were removed. Results are at result.data.data.
• scraper_api sends a GET request with every option in the query string, and adds the wait_until option. At least one of html, markdown, or screenshot must be true. HTML-only requests return a string, and requests with Markdown or a screenshot return an object with one entry per output.
• account is unchanged.

From Version 3.0 to 3.1

Version 3.1.0 adds the account function and the AccountOptions and AccountSummary types. No existing functions changed.

From Version 2

Version 3 renames the public functions and their option types. Request options and the { status_code, data, headers } response are unchanged.

The version 2 names are no longer exported.

From Version 1

fetchHtml and all AI scraper, manual scraper, and results functions (createAiScraper, rerunAiScraper, bulkRerunAiScraper, rerunManualScraper, bulkRerunManualScraper, getAllResults, getResultById) were removed in version 2.

• Replace fetchHtml with scraper_api. It now returns a response wrapper instead of only the API payload, and options use snake_case (for example, geoCode is now geo_code).
• For scrapers and results, call the REST API directly.

Migration from Firecrawl

If you're migrating from the Firecrawl Node SDK, use this mapping to find equivalent MrScraper functions.