Node.js Agent Quickstart

Canonical Firecrawl Node.js quickstart for external agents using search, scrape, and interact.

Canonical Firecrawl Node.js quickstart for agents. Generated from SDK source (firecrawl v4.38.0) and the v2 OpenAPI spec.

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 env var
});

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 post-scrape browser actions. Requires a scrapeId from a prior scrape.

Search

Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with site: in the query string.

Preferred SDK method

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

Example

const results = await client.search("site:docs.firecrawl.dev webhook retries", {
  sources: ["web", "news"],
  limit: 10,
  scrapeOptions: {
    formats: ["markdown"],
    onlyMainContent: true,
  },
});

for (const item of results.web ?? []) {
  console.log(item.url, item.title);
}

Results are grouped by source: results.web, results.news, results.images. Do not access results.data.

Parameters

Parameter	Type	Description
query	string	Search query. Use site:example.com to scope to a domain.
options.sources	("web" | "news" | "images")[]	Which result sources to include.
options.categories	("github" | "developer" | "research" | "pdf")[]	Filter web results by category.
options.includeDomains	string[]	Restrict results to these domains. Mutually exclusive with excludeDomains.
options.excludeDomains	string[]	Exclude results from these domains. Mutually exclusive with includeDomains.
options.limit	number	Max 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.
options.timeout	number	Request timeout in milliseconds.
options.highlights	boolean	Generate query-relevant highlights. Defaults to true.
options.scrapeOptions	ScrapeOptions	Scrape each search result (see Scrape parameters).
options.enterprise	("default" | "anon" | "zdr")[]	Enterprise search options. "zdr" for Zero Data Retention.

Scrape

Why use it

Get structured content from a URL in one or more formats.

Preferred SDK method

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

Example

const doc = await client.scrape("https://example.com/pricing", {
  formats: [
    "markdown",
    "links",
    { type: "json", prompt: "Extract plan names and prices." },
  ],
  onlyMainContent: true,
  waitFor: 1000,
});
console.log(doc.markdown);

Parameters

Parameter	Type	Description
url	string	The URL to scrape.
options.formats	FormatOption[]	Output formats. Strings: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "attributes", "branding", "audio", "video". Objects: { 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 }] }.
options.headers	Record<string, string>	Custom HTTP headers.
options.includeTags	string[]	Only include content from these HTML tags.
options.excludeTags	string[]	Exclude content from these HTML tags.
options.onlyMainContent	boolean	Strip nav, footer, and boilerplate.
options.timeout	number	Timeout in milliseconds.
options.waitFor	number	Wait for page to render (milliseconds).
options.mobile	boolean	Use a mobile viewport.
options.parsers	(string | PDFParser)[]	File parsers. "pdf" or { type: "pdf", mode?: "fast" | "auto" | "ocr", maxPages?, pages?, blocks?, pageMarkers? }.
options.actions	ActionOption[]	Pre-scrape browser actions: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf.
options.location	{ country?: string, languages?: string[] }	Geo/language-aware scraping.
options.skipTlsVerification	boolean	Skip TLS verification.
options.removeBase64Images	boolean	Drop base64 images from markdown.
options.fastMode	boolean	Faster scrapes with reduced fidelity.
options.blockAds	boolean	Block ads and cookie popups.
options.proxy	"basic" | "stealth" | "enhanced" | "auto" | string	Proxy mode or custom URL.
options.maxAge	number	Accept cached data up to this age (milliseconds). Set to 0 to bypass index reuse.
options.minAge	number	Accept cached data only if at least this old (milliseconds).
options.storeInCache	boolean	Cache the result.
options.lockdown	boolean	Serve only previously cached results; never make outbound requests.
options.profile	{ name: string, saveChanges?: boolean }	Persistent browser profile.
options.redactPII	boolean | RedactPIIOptions	Redact personally identifiable information.
options.auditMetadata	{ username: string }	User attribution for SIEM logging.

Interact

Why use it

Control the browser session tied to a scrape job. Use for clicks, form fills, code execution, or natural-language browser instructions. Requires a scrapeId from a prior scrape response.

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");

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

// Code-based interaction
const codeResult = await client.interact(jobId, {
  code: "console.log(await page.title());",
  language: "node",
  timeout: 60,
});

// Stop the session when done
await client.stopInteraction(jobId);

Parameters

Parameter	Type	Description
jobId	string	Scrape job ID from document.metadata.scrapeId.
args.code	string	Code to execute in the browser session. At least one of code or prompt required.
args.prompt	string	Natural-language instruction for the browser agent. At least one of code or prompt required.
args.language	"python" | "node" | "bash"	Runtime for code execution. Defaults to "node".
args.timeout	number	Execution timeout in seconds.

client.stopInteraction(jobId) ends the browser session. Returns { success, sessionDurationMs?, creditsBilled?, error? }.

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 in formats (for json or changeTracking) are converted to JSON Schema by the SDK.
• "json" as a plain string in formats is rejected — use { type: "json", prompt?, schema? }.
• 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