Node.js Agent Quickstart

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

Firecrawl Node.js Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (firecrawl v4.38.0) and the v2 OpenAPI spec. Method names, parameters, and types match the SDK public API.

Install

npm install firecrawl

Requires Node.js >= 22.

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:, 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", {
  sources: ["web"],
  limit: 5,
  scrapeOptions: {
    formats: ["markdown"],
    onlyMainContent: true,
  },
});

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

Wrong turn to avoid: search() does not return { data: [...] }. Web results are in result.web, news in result.news, images in result.images.

Parameters

Parameter	Type	Description
query	string	Search query. Use site:example.com to limit to a domain.
options.sources	("web" | "news" | "images")[]	Which source indexes to search.
options.categories	("developer" | "research" | "pdf" | "github")[]	Filter results by category.
options.includeDomains	string[]	Only include these domains. Cannot combine with excludeDomains.
options.excludeDomains	string[]	Exclude these domains. Cannot combine with includeDomains.
options.limit	number	Max results to return.
options.tbs	string	Time-based filter (e.g. qdr:d for past day, qdr:w for past week).
options.location	string	Localized results (e.g. "San Francisco,California,United States").
options.ignoreInvalidURLs	boolean	Drop URLs that cannot be scraped.
options.highlights	boolean	Return query-relevant text highlights. Defaults to true server-side.
options.timeout	number	Request timeout in milliseconds.
options.scrapeOptions	ScrapeOptions	Scrape each search result (see Scrape parameters).
options.enterprise	("default" | "anon" | "zdr")[]	Enterprise search controls.

Scrape

Why use it

Fetch structured content from a URL in one or more formats. Use when you already have the URL.

Preferred SDK method

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

Example

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

console.log(doc.markdown);
console.log(doc.json);

Parameters

Parameter	Type	Description
url	string	URL to scrape.
options.formats	FormatOption[]	Output formats (see below).
options.headers	Record<string, string>	Custom request headers.
options.includeTags	string[]	Include only these HTML tags.
options.excludeTags	string[]	Exclude these HTML tags.
options.onlyMainContent	boolean	Strip nav, footer, 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	("pdf" | PDFParser)[]	File parsing controls (e.g. { type: "pdf", mode: "auto", maxPages: 5 }).
options.actions	ActionOption[]	Pre-scrape browser actions (click, wait, write, press, scroll, scrape, executeJavascript, screenshot, 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"	Proxy mode.
options.maxAge	number	Use cached data up to this age (milliseconds).
options.storeInCache	boolean	Cache the result.
options.lockdown	boolean	Serve only cached results; never make outbound request.
options.profile	{ name: string; saveChanges?: boolean }	Persistent browser profile across scrapes and interactions.

Format options:

String formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "attributes", "branding", "audio", "video".

Object formats:

• { type: "json", prompt?: string, schema?: object } — at least one of prompt or schema required.
• { type: "question", question: string } — question-answer extraction.
• { type: "highlights", query: string } — relevant source-text extraction.
• { type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width, height } }
• { type: "changeTracking", modes: ("git-diff" | "json")[], schema?, prompt?, tag? } — modes required.
• { type: "attributes", selectors: { selector: string, attribute: string }[] }

Interact

Why use it

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

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.",
});

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

// Clean up
await client.stopInteraction(jobId);

Parameters

Parameter	Type	Description
jobId	string	Scrape job ID from document.metadata.scrapeId.
args.code	string	Code to run in the browser session.
args.prompt	string	Natural-language instruction for the browser agent.
args.language	"python" | "node" | "bash"	Runtime for code execution. Default: "node".
args.timeout	number	Execution timeout in seconds.

At least one of code or prompt must be provided.

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

Notes

• Deprecated aliases: scrapeExecute → interact; stopInteractiveBrowser / deleteScrapeBrowser → stopInteraction.
• The default Firecrawl export is the v2 client; v1 remains under client.v1.
• Zod schemas passed in formats (for json or changeTracking) are auto-converted to JSON Schema by the SDK, and the return type narrows accordingly.
• The SDK auto-resumes scrapes for large documents (PDFs) that outlive the request window (up to 5 retries / 20 minutes).
• 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