Node Agent Quickstart

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

Firecrawl Node Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (@mendable/firecrawl-js) and the OpenAPI spec. Use this file to get an agent calling Firecrawl correctly in one pass.

Install

npm install @mendable/firecrawl-js

Requires Node >= 22.

Authenticate

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

const app = new Firecrawl("fc-YOUR_API_KEY");
// or read from env automatically:
const app = new Firecrawl(); // uses FIRECRAWL_API_KEY env var

Constructor accepts a string (API key) or an options object:

const app = new Firecrawl({
  apiKey: "fc-...",         // optional; falls back to FIRECRAWL_API_KEY
  apiUrl: "https://...",    // optional; falls back to FIRECRAWL_API_URL, then https://api.firecrawl.dev
  timeoutMs: 30000,         // optional; per-request timeout in ms
  maxRetries: 3,            // optional
  backoffFactor: 0.5,       // optional
});

No API key is required for scrape, search, and interact — they fall back to a keyless free tier (rate-limited per IP).

When To Use What

• search: Start with a text query and need to discover relevant URLs and content across the web.
• scrape: Already have a URL and want page content (markdown, HTML, structured JSON, screenshots, etc.).
• interact: The page needs clicks, form fills, or post-scrape browser actions — run code or a prompt against the live browser session.

Search

Why use it

Search the web and optionally scrape each result. Returns categorized results (web, news, images) with optional content scraping.

Preferred SDK method

app.search(query, options?)

Example

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

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

Parameters

Parameter	Type	Description
query	string	Required. The search query.
limit	number	Max number of results. Must be > 0.
sources	("web" | "news" | "images")[]	Which result sources to include.
categories	("github" | "research" | "pdf" | "developer")[]	Narrow web results by category.
includeDomains	string[]	Only include results from these domains. Mutually exclusive with excludeDomains.
excludeDomains	string[]	Exclude results from these domains.
tbs	string	Time-based search filter (e.g. "qdr:d" for past day, "qdr:w" for past week).
location	string	Location string for geo-targeting.
country	string	ISO 3166-1 alpha-2 country code.
ignoreInvalidURLs	boolean	Ignore invalid URLs in results.
timeout	number	Timeout in milliseconds. Must be > 0.
highlights	boolean	Generate query-relevant highlights. Defaults to true.
scrapeOptions	ScrapeOptions	Full scrape options applied to each result page.
enterprise	("default" | "anon" | "zdr")[]	Enterprise options (zero data retention, anonymized search).
threatProtection	ThreatProtectionOptions	Enterprise per-request threat protection config.
integration	string	Integration identifier.

Return type: SearchData with properties .web, .news, .images. Accessing .data throws with guidance to use the named properties instead.

Scrape

Why use it

Fetch a single URL and extract content in various formats: markdown, HTML, structured JSON, screenshots, audio, video, and more. Handles JavaScript rendering, ad blocking, proxies, and caching.

Preferred SDK method

app.scrape(url, options?)

Example

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

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

Parameters

Parameter	Type	Description
url	string	Required. The URL to scrape.
formats	FormatOption[]	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "attributes", "audio", "video", "branding", "product", "menu", "changeTracking". Also accepts object forms for json, screenshot, changeTracking, attributes, question, highlights.
headers	Record<string, string>	Custom HTTP headers for the request.
includeTags	string[]	HTML tags to include in extraction.
excludeTags	string[]	HTML tags to exclude from extraction.
onlyMainContent	boolean	Strip boilerplate (nav, footer, etc.).
timeout	number	Server-side timeout in milliseconds.
waitFor	number	Wait before scraping in milliseconds (for JS rendering).
mobile	boolean	Emulate a mobile viewport.
parsers	(string | PDFParser)[]	Parser config (e.g. PDF mode, maxPages, blocks).
actions	ActionOption[]	Browser actions: wait, click, write, press, scroll, scrape, executeJavascript, screenshot, pdf.
location	LocationConfig	{ country?: string, languages?: string[] } for geo-targeting.
skipTlsVerification	boolean	Skip TLS certificate checks.
removeBase64Images	boolean	Strip base64-encoded images from output.
fastMode	boolean	Enable fast mode (less rendering, faster response).
blockAds	boolean	Block ads and cookie popups.
proxy	string	Proxy tier: "basic", "stealth", "enhanced", "auto", or a custom string.
maxAge	number	Max age in ms of cached content. 0 bypasses the cache.
storeInCache	boolean	Store the result in Firecrawl’s cache.
lockdown	boolean	Only serve cached results; never make an outbound request.
redactPII	boolean | RedactPIIOptions	Redact personally identifiable information.
threatProtection	ThreatProtectionOptions	Enterprise per-request threat config.
auditMetadata	{ username: string }	SIEM logging attribution.
profile	{ name: string, saveChanges?: boolean }	Persistent browser profile across sessions.
integration	string	Integration identifier.
autoResume	boolean	SDK-only. Auto-resume large docs that outlive the request window. Default: true.

Interact

Why use it

Execute code or a natural-language prompt against the live browser session from a previous scrape. Use it to click buttons, fill forms, navigate, or extract dynamic content that only appears after user interaction.

Preferred SDK method

app.interact(jobId, options)

Example

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

const jobId = doc.metadata?.jobId;

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

console.log(result.output);

// When done, stop the session:
await app.stopInteraction(jobId);

Parameters

Parameter	Type	Description
jobId	string	Required. The scrape job ID from a previous scrape call.
code	string	Code to execute in the browser sandbox. At least one of code or prompt is required.
prompt	string	Natural-language prompt to execute. At least one of code or prompt is required.
language	"python" | "node" | "bash"	Language of the code. Defaults to "node".
timeout	number	Execution timeout in seconds.

Stop the session when done:

await app.stopInteraction(jobId);

Notes

• All parameter names use camelCase (e.g. onlyMainContent, skipTlsVerification).
• SearchData uses .web, .news, .images — accessing .data throws an error with migration guidance.
• Deprecated aliases (use the preferred names above):
  • scrapeUrl → scrape
  • scrapeExecute → interact
  • stopInteractiveBrowser / deleteScrapeBrowser → stopInteraction
• The QueryFormat ({ type: "query", prompt, mode }) is deprecated in favor of QuestionFormat or HighlightsFormat.

Source Of Truth

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