Node.js Agent Quickstart

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

Firecrawl Node.js Agent Quickstart

This is the canonical quickstart for external agents integrating with Firecrawl using the official Node.js/TypeScript SDK. Generated from SDK source and OpenAPI spec.

Install

npm install @mendable/firecrawl-js

Authenticate

import Firecrawl from "@mendable/firecrawl-js";

const client = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

Constructor options:

Option	Type	Default	Description
apiKey	string | null	FIRECRAWL_API_KEY env var	API key. Omit for keyless free tier (rate-limited per IP).
apiUrl	string | null	https://api.firecrawl.dev	Base URL. Falls back to FIRECRAWL_API_URL env var.
timeoutMs	number	—	Per-request timeout in milliseconds.
maxRetries	number	—	Max automatic retries for transient failures.
backoffFactor	number	—	Exponential backoff factor for retries.

When To Use What

• search — Use when you start with a query and need to discover relevant pages. Returns search results grouped by source type, optionally with scraped content.
• scrape — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats.
• interact — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox.

Search

Why use it

Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL.

Preferred SDK method

client.search(query, options?)

Example

const results = await client.search("firecrawl web scraping API", {
  limit: 5,
  scrapeOptions: { formats: ["markdown"] },
});

for (const item of results.web ?? []) {
  console.log(item.url, item.markdown?.slice(0, 200));
}

Parameters

All parameters are optional unless noted.

Parameter	Type	Description
query	string	Required (positional). The search query.
sources	Array<"web" | "news" | "images" | { type: ... }>	Source types to search.
categories	Array<"github" | "research" | "pdf" | "developer" | { type: ... }>	Filter by category.
includeDomains	string[]	Restrict results to these domains. Mutually exclusive with excludeDomains.
excludeDomains	string[]	Exclude results from these domains.
limit	number	Max results to return.
tbs	string	Time-based search filter (e.g. "qdr:d" for past day, "qdr:w" for past week).
location	string	Geographic location for results.
ignoreInvalidURLs	boolean	Exclude URLs invalid for other Firecrawl endpoints.
timeout	number	Timeout in milliseconds.
highlights	boolean	Generate query-relevant highlights.
scrapeOptions	ScrapeOptions	Options applied when scraping each result. See Scrape parameters.
enterprise	Array<"default" | "anon" | "zdr">	Enterprise zero data retention options.
threatProtection	ThreatProtectionOptions	Per-request threat protection override.
integration	string	Integration identifier.
origin	string	Request origin tag.

Scrape

Why use it

Fetch and extract content from a single URL. Use when you have a specific page to read.

Preferred SDK method

client.scrape(url, options?)

Example

const doc = await client.scrape("https://example.com", {
  formats: ["markdown", "links"],
  onlyMainContent: true,
});

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

Parameters

All parameters are optional unless noted.

Parameter	Type	Description
url	string	Required (positional). The URL to scrape.
formats	FormatOption[]	Output formats. String values: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "attributes", "branding", "product", "menu", "audio", "video". Object variants: { type: "json", schema?, prompt? }, { type: "screenshot", fullPage?, quality?, viewport? }, { type: "changeTracking", modes, schema?, prompt?, tag? }, { type: "attributes", selectors }, { type: "question", question }, { type: "highlights", query }.
headers	Record<string, string>	Custom HTTP headers to send with the request.
includeTags	string[]	HTML tags to include exclusively.
excludeTags	string[]	HTML tags to exclude.
onlyMainContent	boolean	Only return main content, excluding navbars/footers.
timeout	number	Timeout in milliseconds.
waitFor	number	Delay in ms before fetching content.
mobile	boolean	Emulate a mobile device.
parsers	Array<string | { type: "pdf", mode?, maxPages? }>	File processing parsers. PDF modes: "fast", "auto", "ocr".
actions	ActionOption[]	Browser actions to perform before scraping. Types: wait, screenshot, click, write, press, scroll, scrape, executeJavascript, pdf.
location	{ country?: string, languages?: string[] }	Geolocation for proxy routing.
skipTlsVerification	boolean	Skip TLS certificate verification.
removeBase64Images	boolean	Remove base64 images from output.
fastMode	boolean	Faster scraping with reduced accuracy.
useMock	string	Use a mock response.
blockAds	boolean	Block ads and cookie popups.
proxy	"basic" | "stealth" | "enhanced" | "auto" | string	Proxy mode.
maxAge	number	Use cached result if younger than this (ms).
minAge	number	Minimum cache age (ms). Set to 1 for any cached data.
storeInCache	boolean	Whether to cache the result.
lockdown	boolean	Serve only cached results. No outbound request.
redactPII	boolean | { mode?, entities?, replaceStyle? }	Redact personally identifiable information. Modes: "accurate", "aggressive", "fast".
threatProtection	ThreatProtectionOptions	Per-request threat protection override.
auditMetadata	{ username: string }	User attribution for SIEM logging.
profile	{ name: string, saveChanges?: boolean }	Persistent browser storage profile.
integration	string	Integration identifier.
origin	string	Request origin tag.

Interact

Why use it

Execute code or natural-language prompts in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data.

Preferred SDK method

client.interact(jobId, args)

Example

const doc = await client.scrape("https://example.com", {
  formats: ["markdown"],
});

const jobId = doc.metadata?.jobId;

const result = await client.interact(jobId, {
  code: "document.querySelector('button.load-more')?.click();",
  language: "node",
  timeout: 30,
});

console.log(result.stdout);

Parameters

Parameter	Type	Description
jobId	string	Required (positional). The scrape job ID from a prior scrape.
code	string	Code to execute in the browser sandbox. Required if prompt is not provided.
prompt	string	Natural-language instruction for the browser agent. Required if code is not provided.
language	"python" | "node" | "bash"	Runtime language for code.
timeout	number	Execution timeout in seconds (1-300).
origin	string	Request origin tag.

Related method

client.stopInteraction(jobId)

Stops the interactive browser session and returns billing info.

Notes

• Naming style: All parameters use camelCase.
• Deprecated aliases:
  • scrapeUrl() → use scrape() instead.
  • scrapeExecute() → use interact() instead.
  • stopInteractiveBrowser() and deleteScrapeBrowser() → use stopInteraction() instead.
• Async client: The SDK is async by default (all methods return Promises).
• Zod schemas: The json format accepts Zod schemas in addition to plain JSON Schema objects for the schema field.

Source Of Truth

• 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