Skip to content

Getting Started with the Node.js Web Scraping SDK

This walkthrough moves from setup to three common request patterns: pulling one field out of a page with a CSS selector, stepping up the proxy route when a site refuses ordinary requests, and asking for page content as Markdown so an LLM pipeline can consume it.

OUTPUT FORMATSHTMLJSONMarkdown

An API key is required. Rather than pasting the key into source files, the examples expect it to be present in an environment variable, which keeps the secret out of version control. The installable package and the client class are referenced by their exact identifiers in the accompanying code modules.

Check the runtime, install the package, and protect the key

Three things need to be in place before any request code is written. The runtime has to be Node.js 24 or newer, since SDK version 2.0.0 depends on it. The SDK package must be installed through npm or another Node.js package manager. And an API key must be available to the process as an environment variable, never written directly into the code, so that a stray commit cannot leak it. The examples construct the client from that environment variable; the precise package name, variable name, and constructor call appear in the code modules rather than in this prose.

Extract a single field with a CSS selector

For a targeted extraction, call htmlApi with the target URL and extract_rules that map a field name to a CSS selector. In the example, the field page_heading uses the h1 selector. A successful call returns status 200, and decoding the response data produces a JSON object containing that heading text. This pattern is useful when you need only one or a few known elements rather than the whole page. Check the status first, then decode the payload, and keep the error handler around the request so failures are visible instead of silent.

Escalate from premium to stealth proxies only when blocked

Proxy choice is an escalation decision, not a default setting. Start with the standard route. If a difficult site blocks you, add premium_proxy: true to the params object. If premium routing is still blocked, enable stealth_proxy: true. Budget for the trade-off: both premium and stealth routing consume more API credits than the default proxy, so enable them only for pages that need them rather than across every request.

Request Markdown for LLM and retrieval workflows

When the downstream consumer is a language model or a retrieval pipeline, Markdown is often easier to consume than raw HTML. Set return_page_markdown: true and let the backend perform the conversion. The example returns status 200 followed by the main page content rendered as Markdown, including a heading and a short feature list. Use this mode when readability and structure matter more than preserving original markup.

A decision checklist for your first implementation

A dependable first build follows a fixed sequence. Confirm the runtime is Node.js 24 or newer, install the SDK package, make the API key available as an environment variable, and run a single CSS-selector extraction while checking that the response status is 200. Only after that should premium and stealth routing be tried, and only against pages that reject the default route. Markdown output comes last, once the downstream consumer actually needs structured text. The same request pattern also covers JavaScript rendering and extraction driven by CSS selectors or AI LLM prompts, each governed by an API parameter described in the full documentation. A free trial is available; the current credit allowance and terms are set by the service owner and should be confirmed before relying on a specific number.

Choose the request option by goal
SituationParameter to setTrade-off
A known element is neededextract_rules with a CSS selectorReturns only the mapped fields
A difficult site blocks the default routepremium_proxy: trueHigher credit use than the default
Premium routing is still blockedstealth_proxy: trueHigher credit use than the default
Page content is needed as Markdownreturn_page_markdown: trueConversion happens server-side

Premium and stealth routing consume more API credits than the default proxy.

Frequently asked questions

What do I need before the first Node.js request?

Three things: a Node.js runtime at version 24 or newer, the SDK package installed through npm or a comparable package manager, and an API key supplied through an environment variable instead of being embedded in source files. The client is then constructed from that environment variable. The exact package name, variable name, and constructor expression are given in the accompanying code modules.

When should I switch proxy options?

The default route is the starting point. When a site blocks that route, premium_proxy: true can be enabled first; if blocking continues, stealth_proxy: true can be enabled. Both premium and stealth routes use more API credits than the default.

How do I request Markdown instead of extracted fields?

Add return_page_markdown: true to the request parameters. The service performs the conversion server-side, so the Node.js code only needs to request that output format and decode the response.

200
{"page_heading": "The Best Web Scraping API to Avoid Getting Blocked"}