Firecrawl Node.js Agent Quickstart

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

Install

npm install firecrawl

Requires Node.js 22+.

Authenticate

import Firecrawl from 'firecrawl';

const app = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

Or set the FIRECRAWL_API_KEY environment variable and omit apiKey:

const app = new Firecrawl();

Constructor options:

Option	Type	Default
`apiKey`	`string \| null`	`process.env.FIRECRAWL_API_KEY`
`apiUrl`	`string \| null`	`"https://api.firecrawl.dev"`
`timeoutMs`	`number`	—
`maxRetries`	`number`	—
`backoffFactor`	`number`	—

When To Use What

search: Start with a query, discover relevant URLs, and get their content in one call.
scrape: You already have a URL and want its page content as markdown, HTML, JSON, or other formats.
interact: The page needs clicks, form fills, or post-scrape browser actions on a live session.

Search

Why use it

Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call.

Preferred SDK method

search(query, options?)

Example

const results = await app.search("firecrawl web scraping", { limit: 5 });

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

Parameters

Parameter	Type	Description
`query`	`string`	Required. Search query (max 500 chars).
`limit`	`number`	Max results per source type. Must be positive.
`sources`	`Array<"web" \| "news" \| "images" \| {type: string}>`	Sources to search. Default: `[{type: "web"}]`.
`categories`	`Array<"github" \| "research" \| "pdf" \| "developer">`	Category filters.
`includeDomains`	`string[]`	Restrict to these domains. Cannot combine with `excludeDomains`.
`excludeDomains`	`string[]`	Exclude these domains. Cannot combine with `includeDomains`.
`tbs`	`string`	Time-based filter (e.g. `"qdr:d"` past day, `"qdr:w"` past week, `"qdr:m"` past month).
`location`	`string`	Geo-targeting location string.
`ignoreInvalidURLs`	`boolean`	Exclude invalid URLs from results.
`timeout`	`number`	Timeout in ms. 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`	Per-request threat protection override.
`integration`	`string`	Integration identifier.
`origin`	`string`	Origin label for telemetry.

Response groups results by source: results.web, results.news, results.images, results.developer.

Scrape

Why use it

Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats.

Preferred SDK method

scrape(url, options?)

Example

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

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

Parameters

Parameter	Type	Description
`url`	`string`	Required. URL to scrape.
`formats`	`FormatOption[]`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Also accepts config objects (see below). Default: `["markdown"]`.
`headers`	`Record<string, string>`	Custom HTTP headers.
`includeTags`	`string[]`	HTML tags to include.
`excludeTags`	`string[]`	HTML tags to exclude.
`onlyMainContent`	`boolean`	Strip navbars, footers, boilerplate. Default: `true`.
`timeout`	`number`	Timeout in ms. Default: `60000`. Min: `1000`, Max: `300000`.
`waitFor`	`number`	Extra delay in ms before fetching content.
`mobile`	`boolean`	Emulate a mobile device.
`parsers`	`Array<string \| {type: "pdf", mode?: "fast"\|"auto"\|"ocr", maxPages?: number}>`	File processing controls. Default: `["pdf"]`.
`actions`	`ActionOption[]`	Browser actions before content capture: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`.
`location`	`{country?: string, languages?: string[]}`	Geo settings. Country defaults to `"US"`.
`skipTlsVerification`	`boolean`	Skip TLS certificate verification.
`removeBase64Images`	`boolean`	Remove base64 images from markdown. Default: `true`.
`fastMode`	`boolean`	Enable fast mode.
`blockAds`	`boolean`	Block ads and cookie popups. Default: `true`.
`proxy`	`"basic" \| "stealth" \| "enhanced" \| "auto"`	Proxy type. `"enhanced"` costs up to 5 credits. Default: `"auto"`.
`maxAge`	`number`	Cache threshold in ms. Returns cached version if younger. Default: 2 days.
`minAge`	`number`	Cache-only mode minimum age in ms.
`storeInCache`	`boolean`	Store result in Firecrawl cache. Default: `true`.
`lockdown`	`boolean`	Cache-only, no outbound requests.
`redactPII`	`boolean \| RedactPIIOptions`	Redact PII. Pass `true` for defaults or `{mode?: "accurate"\|"aggressive"\|"fast", entities?: string[], replaceStyle?: "tag"\|"mask"\|"remove"}`.
`threatProtection`	`ThreatProtectionOptions`	Threat protection override with `mode`, `riskScoreThreshold`, `blacklist`, `whitelist`, `blockedTlds`, `failurePolicy`.
`auditMetadata`	`{username: string}`	SIEM logging user attribution.
`profile`	`{name: string, saveChanges?: boolean}`	Persistent browser profile.
`integration`	`string`	Integration identifier.
`origin`	`string`	Origin label.

Format config objects

Format	Config fields
`json`	`{type: "json", schema?: object, prompt?: string}` — structured extraction with optional JSON Schema and prompt.
`screenshot`	`{type: "screenshot", fullPage?: boolean, quality?: number, viewport?: {width, height}}`
`changeTracking`	`{type: "changeTracking", modes: ("git-diff"\|"json")[], schema?: object, prompt?: string, tag?: string}`
`question`	`{type: "question", question: string}` — ask a question about the page.
`highlights`	`{type: "highlights", query: string}` — extract text relevant to a query.
`attributes`	`{type: "attributes", selectors: [{selector: string, attribute: string}]}`

Interact

Why use it

Control a live browser session tied to a scrape job. Click buttons, fill forms, navigate, and extract dynamic content using code or natural-language prompts.

Preferred SDK method

interact(jobId, args)

Example

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

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

await app.stopInteraction(scrapeId);

Parameters

Parameter	Type	Description
`jobId`	`string`	Required. Scrape job ID from `result.metadata.scrapeId`.
`code`	`string`	Code to execute in the browser sandbox. One of `code` or `prompt` required.
`prompt`	`string`	Natural-language instruction. One of `code` or `prompt` required.
`language`	`"python" \| "node" \| "bash"`	Runtime for code execution. Default: `"node"`.
`timeout`	`number`	Execution timeout in seconds. Min: 1, Max: 300.
`origin`	`string`	Origin label for telemetry.

Stop the session when done:

await app.stopInteraction(scrapeId);

Notes

Parameter names use camelCase (e.g. onlyMainContent, includeTags, scrapeOptions).
includeDomains and excludeDomains on search are mutually exclusive.
Deprecated aliases (do not use in new code):
- scrapeExecute() → use interact()
- stopInteractiveBrowser() / deleteScrapeBrowser() → use stopInteraction()
- scrapeUrl() → use scrape()
- crawlUrl() → use crawl()
- mapUrl() → use map()

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

Get Started

Core Endpoints

More

Quickstarts

Agent Quickstarts

Developer Guides

Webhooks

Use Cases

Other

Contributing

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

Format config objects

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

​Format config objects

​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

Format config objects

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth