Node.js Agent Quickstart

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

Firecrawl Node.js Agent Quickstart

This file is the canonical quickstart for external agents integrating Firecrawl via 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 client = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

The API key can also be set via the FIRECRAWL_API_KEY environment variable. If omitted, the client falls back to keyless free tier (rate-limited per IP).

When To Use What

• search: Use when you start with a query and need to discover relevant URLs and their content. Returns results from web, news, and image sources.
• scrape: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
• interact: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

Search

Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

Preferred SDK method

client.search(query, options?)

Example

const results = await client.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	The search query (first argument, required).
sources	Array<"web" | "news" | "images">	Which search indices to query.
categories	Array<"github" | "research" | "pdf" | "developer">	Filter results by category.
includeDomains	string[]	Restrict results to these domains. Cannot be used with excludeDomains.
excludeDomains	string[]	Exclude results from these domains. Cannot be used with includeDomains.
limit	number	Maximum number of results to return. Server default: 10.
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 search.
ignoreInvalidURLs	boolean	Ignore invalid URLs in results.
timeout	number	Timeout in milliseconds. Server default: 60000.
highlights	boolean	Generate query-relevant highlights. Default: true.
scrapeOptions	ScrapeOptions	Nested scrape configuration applied to each result.
enterprise	Array<"default" | "anon" | "zdr">	Enterprise search options for Zero Data Retention.
threatProtection	ThreatProtectionOptions	Per-request threat protection overrides.
integration	string	Integration identifier.
origin	string	Origin identifier.

Scrape

Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

Preferred SDK method

client.scrape(url, options?)

Example

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

console.log(doc.markdown);

Parameters

Parameter	Type	Description
url	string	The URL to scrape (first argument, required).
formats	FormatOption[]	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "attributes", "branding", "product", "menu", "audio", "video", or typed objects (see below). Server default: ["markdown"].
onlyMainContent	boolean	Strip boilerplate, keep main content only. Server default: true.
headers	Record<string, string>	Custom HTTP headers to send with the request.
includeTags	string[]	HTML tags to exclusively include.
excludeTags	string[]	HTML tags to exclude.
timeout	number	Timeout in milliseconds. Min: 1000, max: 300000. Server default: 60000.
waitFor	number	Delay in milliseconds before fetching content. Server default: 0.
mobile	boolean	Emulate mobile device viewport and user-agent. Server default: false.
parsers	Array<string | PdfParser>	Parser configurations (e.g. "pdf" or { type: "pdf", mode: "auto", maxPages: 10 }). Server default: ["pdf"].
actions	ActionOption[]	Browser automation actions to perform before scraping. See Actions below.
location	LocationConfig	Location settings: { country?: string, languages?: string[] }. Default country: "US".
skipTlsVerification	boolean	Skip TLS certificate verification.
removeBase64Images	boolean	Remove base64-encoded images from markdown output. Server default: true.
fastMode	boolean	Enable fast mode for faster scrapes with reduced accuracy.
blockAds	boolean	Block advertisements and cookie popups. Server default: true.
proxy	"basic" | "stealth" | "enhanced" | "auto"	Proxy tier. "basic": fast. "enhanced": advanced anti-bot (up to 5 credits). "auto": tries basic first, retries with enhanced. Server default: "auto".
maxAge	number	Use cached result if younger than this many milliseconds. Server default: 172800000 (2 days).
minAge	number	Cache-only mode. Set to 1 for any cached data. Returns 404 on cache miss.
storeInCache	boolean	Cache the scrape result. Server default: true.
lockdown	boolean	Only serve cached results, never make outbound requests.
redactPII	boolean | RedactPIIOptions	Redact personally identifiable information. Pass true for defaults or an options object.
threatProtection	ThreatProtectionOptions	Per-request threat protection overrides.
auditMetadata	{ username: string }	User attribution for SIEM logging.
profile	{ name: string, saveChanges?: boolean }	Persistent browser profile for session continuity.
integration	string	Integration identifier.
origin	string	Origin identifier.
useMock	string	Use mock data.

Format objects

Type	Fields
JsonFormat	{ type: "json", prompt?: string, schema?: object | ZodSchema }
ScreenshotFormat	{ type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width, height } }
ChangeTrackingFormat	{ type: "changeTracking", modes: ("git-diff" | "json")[], schema?: object, prompt?: string, tag?: string }
AttributesFormat	{ type: "attributes", selectors: { selector: string, attribute: string }[] }
QuestionFormat	{ type: "question", question: string }
HighlightsFormat	{ type: "highlights", query: string }

Actions

Type	Fields
wait	{ type: "wait", milliseconds?: number, selector?: string }
screenshot	{ type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width, height } }
click	{ type: "click", selector: string }
write	{ type: "write", text: string }
press	{ type: "press", key: string }
scroll	{ type: "scroll", direction: "up" | "down", selector?: string }
scrape	{ type: "scrape" }
executeJavascript	{ type: "executeJavascript", script: string }
pdf	{ type: "pdf", format?: string, landscape?: boolean, scale?: number }

Interact

Why use it

Execute code or send natural-language prompts in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts.

Preferred SDK method

client.interact(jobId, args)

Example

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

const jobId = doc.metadata?.jobId;

const result = await client.interact(jobId, {
  code: "document.title",
  language: "node",
});

console.log(result.stdout);

await client.stopInteraction(jobId);

Parameters

Parameter	Type	Description
jobId	string	The scrape job ID (first argument, required).
code	string	Code to execute in the browser sandbox.
prompt	string	Natural-language instruction for the browser agent.
language	"python" | "node" | "bash"	Execution language. Server default: "node".
timeout	number	Execution timeout in seconds. Range: 1-300. Server default: 30.
origin	string	Origin identifier for telemetry.

Use client.stopInteraction(jobId) to end the browser session when done.

Notes

• Naming style: All parameters use camelCase.
• Deprecated aliases: scrapeUrl() is deprecated in favor of scrape(). scrapeExecute() is deprecated in favor of interact(). stopInteractiveBrowser() and deleteScrapeBrowser() are deprecated in favor of stopInteraction().
• Zod schema support: The scrape() method accepts Zod schemas in JsonFormat and will narrow the return type accordingly.
• Async: All methods return Promises.

Source Of Truth

• /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