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.
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.
| Situation | Parameter to set | Trade-off |
|---|---|---|
| A known element is needed | extract_rules with a CSS selector | Returns only the mapped fields |
| A difficult site blocks the default route | premium_proxy: true | Higher credit use than the default |
| Premium routing is still blocked | stealth_proxy: true | Higher credit use than the default |
| Page content is needed as Markdown | return_page_markdown: true | Conversion 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"}