Node.js Agent Quickstart

Canonical Firecrawl Node.js quickstart for external agents. Aligned with firecrawl v4.32.0 (firecrawl/apps/js-sdk/firecrawl) and the v2 OpenAPI spec. Method names, parameters, and types match the SDK public API.

Install

npm install firecrawl

Authenticate

import { Firecrawl } from "firecrawl";

const client = new Firecrawl({
  apiKey: process.env.FIRECRAWL_API_KEY,
  // apiUrl: "https://api.firecrawl.dev" // optional; falls back to FIRECRAWL_API_URL or cloud default
});

When To Use What

search: use when you start with a query and need discovery.
scrape: use when you already have a URL and want page content.
interact: use when the page needs clicks, forms, or other browser actions after a scrape has created a session. For multi-step interactive flows, prefer interact over scrape-time actions.

Search

Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can constrain results to a site with site:, for example site:docs.firecrawl.dev crawl webhooks.

Preferred SDK method

client.search(query, options?) → Promise<SearchData>

Example

const results = await client.search("site:docs.firecrawl.dev webhook retries");
for (const item of results.web ?? []) {
  console.log(item.url, item.title);
}

Parameters

Parameter	Type	Description
`query`	`string`	The search query. Use `site:example.com` to limit results to a domain.
`options.sources`	`("web" \| "news" \| "images")[]`	Which search sources to query.
`options.categories`	`("github" \| "research" \| "pdf" \| "developer")[]`	Filter results by category.
`options.includeDomains`	`string[]`	Restrict results to these domains. Mutually exclusive with `excludeDomains`.
`options.excludeDomains`	`string[]`	Exclude these domains. Mutually exclusive with `includeDomains`.
`options.limit`	`number`	Cap the number of results.
`options.tbs`	`string`	Time-based filter (e.g. `qdr:d`, `qdr:w`, `sbd:1,qdr:m`).
`options.location`	`string`	Location string for localized results.
`options.ignoreInvalidURLs`	`boolean`	Drop URLs that cannot be scraped by other endpoints.
`options.timeout`	`number`	Request timeout in milliseconds.
`options.highlights`	`boolean`	Generate query-relevant highlights. Defaults to true server-side.
`options.scrapeOptions`	`ScrapeOptions`	Scrape each search result (see Scrape parameters).
`options.enterprise`	`("default" \| "anon" \| "zdr")[]`	Enterprise options. `"zdr"` for zero data retention, `"anon"` for anonymized search.

Return value: SearchData with optional arrays web, news, images, developer. Do not access result.data — it throws an error directing you to use result.web, result.news, etc.

Scrape

Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

Preferred SDK method

client.scrape(url, options?) → Promise<Document>

Example

const doc = await client.scrape("https://docs.firecrawl.dev", {
  formats: ["markdown"]
});
console.log(doc.markdown);

Parameters

Parameter	Type	Description
`url`	`string`	The URL to scrape.
`options.formats`	`FormatOption[]`	Output formats. Plain strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Object formats: `{ type: "json", prompt?, schema? }`, `{ type: "question", question }`, `{ type: "highlights", query }`, `{ type: "screenshot", fullPage?, quality?, viewport? }`, `{ type: "changeTracking", modes, schema?, prompt?, tag? }`, `{ type: "attributes", selectors: [{ selector, attribute }] }`. Note: plain string `"json"` is rejected — use the object form.
`options.headers`	`Record<string, string>`	Custom request headers.
`options.includeTags`	`string[]`	Include only specific HTML tags.
`options.excludeTags`	`string[]`	Exclude specific HTML tags.
`options.onlyMainContent`	`boolean`	Strip nav, footer, and other boilerplate.
`options.timeout`	`number`	Timeout in milliseconds.
`options.waitFor`	`number`	Wait for the page to render (milliseconds).
`options.mobile`	`boolean`	Use a mobile viewport.
`options.parsers`	`("pdf" \| { type: "pdf", mode?, maxPages? })[]`	File parsing controls. PDF modes: `"fast"`, `"auto"`, `"ocr"`.
`options.actions`	`ActionOption[]`	Pre-scrape browser actions. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`.
`options.location`	`{ country?, languages? }`	Geo or language-aware scraping.
`options.skipTlsVerification`	`boolean`	Skip TLS verification.
`options.removeBase64Images`	`boolean`	Drop base64 images from markdown output.
`options.fastMode`	`boolean`	Faster scrapes with reduced fidelity.
`options.blockAds`	`boolean`	Block ads and cookie popups.
`options.proxy`	`"basic" \| "stealth" \| "enhanced" \| "auto"`	Proxy mode.
`options.maxAge`	`number`	Use cached data up to this age (milliseconds).
`options.minAge`	`number`	Use cached data only if at least this old (milliseconds).
`options.storeInCache`	`boolean`	Cache the result.
`options.lockdown`	`boolean`	Only serve cached results, never make an outbound request.
`options.redactPII`	`boolean \| RedactPIIOptions`	Redact personally identifiable information. Options: `mode`, `entities`, `replaceStyle`.
`options.profile`	`{ name, saveChanges? }`	Persistent browser profile shared across scrapes and interactions.
`options.auditMetadata`	`{ username }`	User attribution for SIEM logging.

Interact

Why use it

Use interact for code or natural-language control of the browser session tied to a scrape job (via metadata.scrapeId). The SDK requires at least one of code or prompt. For flows that go beyond quick pre-scrape tweaks, prefer interact over scrape-time actions.

Preferred SDK method

client.interact(jobId, args) → Promise<ScrapeExecuteResponse>

Example

const doc = await client.scrape("https://example.com", { formats: ["markdown"] });
const jobId = doc.metadata?.scrapeId;
if (!jobId) throw new Error("Missing scrapeId from scrape response");

const result = await client.interact(jobId, {
  prompt: "Click the pricing tab and summarize the plans."
});

Parameters

Parameter	Type	Description
`jobId`	`string`	Scrape job ID from `document.metadata.scrapeId`.
`args.code`	`string`	Code to run in the browser session (e.g. Playwright `page` usage). Provide `code` or `prompt` (at least one required).
`args.prompt`	`string`	Natural-language instruction for the browser agent. Provide `code` or `prompt` (at least one required).
`args.language`	`"python" \| "node" \| "bash"`	Runtime language. Default: `"node"`.
`args.timeout`	`number`	Execution timeout in seconds.

Stop session

client.stopInteraction(jobId) → Promise<ScrapeBrowserDeleteResponse> Ends the scrape-bound browser session. Response includes success, sessionDurationMs, creditsBilled.

Notes

Deprecated aliases: scrapeExecute → interact; stopInteractiveBrowser and deleteScrapeBrowser → stopInteraction; scrapeUrl → scrape.
The default Firecrawl export is the v2 client; v1 remains under client.v1.
Zod schemas passed to formats (for json or changeTracking) are converted to JSON Schema by the SDK.
The package declares Node.js >= 22 in engines.

Source Of Truth

firecrawl/apps/js-sdk/firecrawl/package.json
firecrawl/apps/js-sdk/firecrawl/src/index.ts
firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts
firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts
firecrawl-docs/api-reference/v2-openapi.json

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Agent Quickstarts

Cookbooks

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Stop session

Notes

Source Of Truth

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Stop session

​Notes

​Source Of Truth

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Stop session

Notes

Source Of Truth