Firecrawl Node.js Agent Quickstart

Canonical quickstart for external agents integrating with Firecrawl via the Node.js SDK. Generated from SDK source and the OpenAPI spec.

Install

npm install firecrawl

Requires Node.js 22+.

Authenticate

import Firecrawl from "firecrawl";

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

Or use the FIRECRAWL_API_KEY environment variable:

const firecrawl = new Firecrawl();

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

Option	Type	Description
`apiKey`	`string`	API key. Falls back to `FIRECRAWL_API_KEY` env var, then keyless free tier (rate-limited per IP).
`apiUrl`	`string`	Base URL. Defaults to `https://api.firecrawl.dev`.
`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: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content.
scrape: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc.
interact: The page needs post-scrape browser actions — clicking, typing, executing code, or natural-language browser instructions.

Search

Why use it

Discover web pages matching a query. Optionally scrape each result for full content in one call.

Preferred SDK method

firecrawl.search(query, options?)

Example

import Firecrawl from "firecrawl";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });
const results = await firecrawl.search("firecrawl web scraping", { limit: 5 });

for (const result of results.web) {
  console.log(result.title, result.url);
}

Parameters

Parameter	Type	Description
`query`	`string`	Search query. Required (first positional argument).
`limit`	`number`	Max number of results per source type.
`sources`	`Array<"web" \| "news" \| "images">`	Result sources to include. Defaults to `["web"]`.
`categories`	`Array<"github" \| "research" \| "pdf" \| "developer">`	Narrow results by category. Use when you want domain-specific filtering.
`includeDomains`	`string[]`	Restrict to these domains. Mutually exclusive with `excludeDomains`.
`excludeDomains`	`string[]`	Exclude these domains. Mutually exclusive with `includeDomains`.
`tbs`	`string`	Time-based filter. Use `"qdr:h"` (past hour), `"qdr:d"` (day), `"qdr:w"` (week), `"qdr:m"` (month), `"qdr:y"` (year), or custom date ranges.
`location`	`string`	Location string for geo-targeted results (e.g. `"San Francisco,California,United States"`).
`ignoreInvalidURLs`	`boolean`	Skip invalid URLs instead of failing. Useful when piping results to other Firecrawl endpoints.
`timeout`	`number`	Timeout in milliseconds.
`highlights`	`boolean`	Generate query-relevant highlights. Defaults to `true`. Set `false` for raw provider descriptions.
`scrapeOptions`	`ScrapeOptions`	Scrape each result page. Same parameters as the scrape endpoint below.
`enterprise`	`Array<"default" \| "anon" \| "zdr">`	Enterprise options: `"zdr"` for zero data retention, `"anon"` for anonymized search.
`threatProtection`	`ThreatProtectionOptions`	Per-request threat protection override.
`integration`	`string`	Integration identifier for attribution.
`origin`	`string`	Origin identifier.

Results are grouped by source: results.web, results.news, results.images, results.developer.

Scrape

Why use it

Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more.

Preferred SDK method

firecrawl.scrape(url, options?)

Example

const result = await firecrawl.scrape("https://example.com", {
  formats: ["markdown", "links"],
});
console.log(result.markdown);
console.log(result.links);

Parameters

Parameter	Type	Description
`url`	`string`	URL to scrape. Required (first positional argument).
`formats`	`FormatOption[]`	Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Or format objects like `{ type: "json", schema: {...}, prompt: "..." }`, `{ type: "question", question: "..." }`, `{ type: "highlights", query: "..." }`.
`headers`	`Record<string, string>`	Custom HTTP headers for the request. Use for cookies, auth tokens, user-agent.
`includeTags`	`string[]`	Only include content from these HTML tags.
`excludeTags`	`string[]`	Exclude content from these HTML tags.
`onlyMainContent`	`boolean`	Extract only main content, excluding headers/navs/footers.
`timeout`	`number`	Timeout in milliseconds. Min `1000`, max `300000`. Default `60000`.
`waitFor`	`number`	Additional wait in milliseconds before scraping. Use for JS-rendered content.
`mobile`	`boolean`	Emulate a mobile device. Use for responsive pages or mobile-specific content.
`parsers`	`Array`	Parser config. Use `["pdf"]` or `[{ type: "pdf", mode: "fast" \| "auto" \| "ocr", maxPages: number }]`.
`actions`	`ActionOption[]`	Browser actions before scraping: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`.
`location`	`{ country?: string, languages?: string[] }`	Location settings for geo-targeting and language preference.
`skipTlsVerification`	`boolean`	Skip TLS certificate verification.
`removeBase64Images`	`boolean`	Remove base64 images from markdown output.
`fastMode`	`boolean`	Faster scrape with reduced accuracy.
`blockAds`	`boolean`	Block ads and cookie popups.
`proxy`	`"basic" \| "stealth" \| "enhanced" \| "auto"`	Proxy tier. `"auto"` retries with enhanced if basic fails.
`maxAge`	`number`	Max age in ms of cached content for reuse. `0` bypasses cache. Default `172800000` (2 days).
`minAge`	`number`	Cache-only mode. Returns cached data of at least this age in ms. Use `1` to accept any cached data.
`storeInCache`	`boolean`	Store result in Firecrawl cache.
`lockdown`	`boolean`	Serve only cached results, never make outbound requests.
`redactPII`	`boolean \| RedactPIIOptions`	Redact PII from content. Pass `true` for defaults or `{ mode, entities, replaceStyle }`.
`auditMetadata`	`{ username: string }`	User attribution for SIEM logging.
`profile`	`{ name: string, saveChanges?: boolean }`	Persistent browser profile for shared state across sessions.
`threatProtection`	`ThreatProtectionOptions`	Per-request threat protection override.
`integration`	`string`	Integration identifier.
`origin`	`string`	Origin identifier.

Interact

Why use it

Continue interacting with a live browser session after scraping. Execute code or send natural-language prompts to control the page — click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

firecrawl.interact(jobId, args)

Example

const result = await firecrawl.scrape("https://www.amazon.com", { formats: ["markdown"] });
const scrapeId = result.metadata?.scrapeId;

await firecrawl.interact(scrapeId, { prompt: "Search for iPhone 16 Pro Max" });
const response = await firecrawl.interact(scrapeId, {
  prompt: "Click on the first result and tell me the price",
});
console.log(response.output);

await firecrawl.stopInteraction(scrapeId);

Parameters

Parameter	Type	Description
`jobId`	`string`	Scrape job ID. Required (first positional argument). Obtained from `result.metadata.scrapeId` of a previous scrape.
`code`	`string`	Code to execute in the browser session. One of `code` or `prompt` is required.
`prompt`	`string`	Natural-language instruction for the browser agent. One of `code` or `prompt` is required.
`language`	`"python" \| "node" \| "bash"`	Language for code execution. Defaults to `"node"`.
`timeout`	`number`	Execution timeout in seconds (1-300).
`origin`	`string`	Origin identifier.

Call firecrawl.stopInteraction(jobId) to end the browser session when done.

Notes

camelCase parameters: All options use camelCase (e.g. onlyMainContent, includeTags, scrapeOptions).
Zod schema inference: When using { type: "json", schema: zodSchema } in formats, TypeScript narrows the json return type to z.infer<typeof zodSchema>.
SearchData structure: Access results via results.web, results.news, results.images, or results.developer. Accessing results.data throws an error.
Timeout arithmetic: The SDK adds 5000ms to the provided timeout for the HTTP request. For interact, timeout is in seconds (converted to ms internally).
Deprecated aliases: scrapeExecute -> interact, stopInteractiveBrowser / deleteScrapeBrowser -> stopInteraction, scrapeUrl -> scrape.

Source Of Truth

SDK source: firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts, firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts
OpenAPI spec: firecrawl-docs/api-reference/v2-openapi.json

Getting Started

Agent Quickstarts

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

Node.js Agent Quickstart

Firecrawl Node.js Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth

​Firecrawl Node.js Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Notes

​Source Of Truth

Firecrawl Node.js Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth