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

Getting Started

AI Tools

Agent Harnesses

Agent Quickstarts

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