Node.js SDK

The official @mrscraper/sdk package exposes three functions: scraper_api to fetch page content (HTML, Markdown, or screenshots), web_search to get Google 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 Google
  const search = await web_search("python web scraping", { raw: false });
  console.log(search.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 { scraper_api } from "@mrscraper/sdk";

const result = await scraper_api("https://example.com", {
  html: true,
  markdown: true,
  screenshot: true,
  geo_code: "US",
  timeout: 120,
  // token: "optional_override_token"
});
console.log(result.data);

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 get Google search results. The first argument accepts either query text or a full Google search URL.

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

const result = await web_search("python web scraping", {
  raw: false,
  format: "json",
  region: "us",
  language: "en",
  page: 1,
  // token: "optional_override_token"
});
console.log(result.data);

You can also pass a Google search URL. The SDK extracts the q, gl, hl, and start parameters, and any options you pass explicitly override the values from the URL:

const result = await web_search(
  "https://www.google.com/search?q=iphone+17&gl=us&hl=en",
);

Parameters:

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,
  WebSearchOptions,
  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 3.0

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, googleSerp, 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 and googleSerp with web_search. Both now return 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.