Node.js Agent Quickstart

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

Firecrawl Node.js Agent Quickstart

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

Install

npm install @mendable/firecrawl-js

Authenticate

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

const app = new Firecrawl("fc-YOUR_API_KEY");

The API key can also be set via the FIRECRAWL_API_KEY environment variable. Omitting the key uses the keyless free tier (rate-limited per IP).

Client options:

Option	Type	Default	Description
apiKey	string | null	FIRECRAWL_API_KEY env var	API key for authentication
apiUrl	string | null	"https://api.firecrawl.dev"	Base URL for the API
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 ranked results with optional scraping of each result.
• scrape: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats.
• interact: Use when a page needs post-scrape browser actions — clicking, filling forms, running code, or prompting an AI agent in the browser.

Search

Why use it

Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing scrapeOptions.

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.title, item.url);
}

Parameters

Parameter	Type	Description
query	string	Required. The search query (max 500 chars).
limit	number	Max results to return. Must be positive.
sources	Array<"web" | "news" | "images" | { type: string }>	Which result sources to include. Default: web only.
categories	Array<"github" | "research" | "pdf" | object>	Filter results by category.
includeDomains	string[]	Restrict results to these domains. Cannot combine with excludeDomains.
excludeDomains	string[]	Exclude results from these domains. Cannot combine with includeDomains.
tbs	string	Time-based search filter (e.g. "qdr:d" for past day, "qdr:w" for past week).
location	string	Location string for geo-targeted results.
ignoreInvalidURLs	boolean	Ignore invalid URLs in results.
timeout	number	Timeout in milliseconds. Must be positive.
highlights	boolean	Generate query-relevant highlights. Default: true.
scrapeOptions	ScrapeOptions	Scrape options applied to each result page.
enterprise	Array<"default" | "anon" | "zdr">	Enterprise zero data retention options.
threatProtection	ThreatProtectionOptions	Enterprise per-request threat protection override.
integration	string	Integration identifier for tracking.

Returns: SearchData with optional .web, .news, and .images arrays depending on sources.

Scrape

Why use it

Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats.

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

Parameters

Parameter	Type	Description
url	string	Required. The URL to scrape.
formats	FormatOption[]	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "changeTracking", "branding", "product", "menu", "audio", "video", or objects like { type: "question", question: "..." } and { type: "highlights", query: "..." }.
onlyMainContent	boolean	Extract only the main content, excluding headers/navs/footers.
includeTags	string[]	HTML tags to include in output.
excludeTags	string[]	HTML tags to exclude from output.
timeout	number	Timeout in milliseconds (1000–300000).
waitFor	number	Delay in ms before fetching content.
mobile	boolean	Emulate a mobile device.
headers	Record<string, string>	Custom HTTP headers to send with the request.
actions	ActionOption[]	Browser actions to perform before scraping: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf.
parsers	Array<string | PDFParser>	Parser configs. Include "pdf" to extract PDF content to markdown.
location	{ country?: string; languages?: string[] }	Geo-location for proxy routing.
skipTlsVerification	boolean	Skip TLS certificate verification.
removeBase64Images	boolean	Remove base64 images from output.
fastMode	boolean	Enable fast mode (less accuracy).
blockAds	boolean	Block ads and cookie popups.
proxy	"basic" | "stealth" | "enhanced" | "auto"	Proxy tier. auto tries basic first, retries with enhanced on failure.
maxAge	number	Use cached result if younger than this (ms). 0 bypasses cache.
storeInCache	boolean	Store result in Firecrawl cache.
lockdown	boolean	Serve from cache only; never makes outbound request.
redactPII	boolean | RedactPIIOptions	Redact PII from returned content.
auditMetadata	{ username: string }	User attribution for SIEM logging.
profile	{ name: string; saveChanges?: boolean }	Persistent browser profile for session continuity.
integration	string	Integration identifier.
autoResume	boolean	SDK-only. Auto-retry when a large doc outlives the request window. Default: true.
threatProtection	ThreatProtectionOptions	Enterprise per-request threat protection override.

Returns: Document with fields like markdown, html, rawHtml, links, images, screenshot, metadata, etc.

Interact

Why use it

Execute code or send a natural-language prompt in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox.

Preferred SDK method

app.interact(jobId, args)

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.stdout);

Parameters

Parameter	Type	Description
jobId	string	Required. The scrape job ID (from doc.metadata.jobId).
code	string	Code to execute. One of code or prompt is required.
prompt	string	Natural-language instruction for the AI browser agent. One of code or prompt is required.
language	"python" | "node" | "bash"	Execution language. Default: "node".
timeout	number	Execution timeout in seconds (1–300).

Returns: ScrapeExecuteResponse with success, stdout, stderr, result, exitCode, killed, error, and optional liveViewUrl / interactiveLiveViewUrl.

Stop the session:

await app.stopInteraction(jobId);

Notes

• All parameter names use camelCase (e.g. onlyMainContent, skipTlsVerification, scrapeOptions).
• includeDomains and excludeDomains on search are mutually exclusive.
• The SearchData return type has .web, .news, and .images arrays. Accessing .data throws a helpful migration error.
• Deprecated aliases (use the preferred names instead):
  • scrapeUrl() → scrape()
  • scrapeExecute() → interact()
  • stopInteractiveBrowser() / deleteScrapeBrowser() → stopInteraction()

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