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 with Firecrawl via the official Node.js SDK. It is generated from SDK source and the OpenAPI spec.

Install

npm install firecrawl

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

When To Use What

• search — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
• scrape — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
• interact — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

Search

Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

Preferred SDK method

app.search(query, options?)

Example

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

for (const result of results.web) {
  console.log(result.title, result.url);
  console.log(result.markdown); // available when scrapeOptions is set
}

Parameters

Parameter	Type	Description
query	string	The search query (max 500 chars). Required.
limit	number	Max results to return per source type. Default: 10. Range: 1–100.
sources	Array<string | object>	Source types to search: "web", "news", "images", "alexandria". Default: ["web"].
categories	Array<string | object>	Filter results by category: "github", "research", "pdf", "developer", "gov".
includeDomains	string[]	Restrict results to these domains (hostnames only). Cannot combine with excludeDomains.
excludeDomains	string[]	Exclude results from these domains. Cannot combine with includeDomains.
tbs	string	Time-based filter. Predefined: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year). Custom: cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY. Sort by date: sbd:1. Combinable.
location	string	Location for search results.
country	string	ISO 3166-1 alpha-2 country code.
highlights	boolean	Return query-relevant highlights. Default: true.
timeout	number	Timeout in milliseconds.
ignoreInvalidURLs	boolean	Skip invalid URLs instead of failing.
scrapeOptions	ScrapeOptions	Apply scrape options to each search result page to get full content.
domainTools	boolean	Include Alexandria tool contracts matched to result domains.
toolDetail	"compact" | "summary" | "full"	Detail level for returned tool contracts. Default: "compact".
integration	string	Integration identifier.
origin	string	Origin label for telemetry.

Scrape

Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

Preferred SDK method

app.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	The URL to scrape. Required.
formats	FormatOption[]	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", "summary", "audio", "video", "changeTracking", "branding", "product", "menu", "question", "highlights". Default: ["markdown"]. Some accept config objects.
onlyMainContent	boolean	Strip headers, navs, footers. Deterministic HTML filter, no LLM. Default: true.
onlyCleanContent	boolean	Additional LLM-based boilerplate removal pass. Default: false.
includeTags	string[]	Only include content from these HTML tags.
excludeTags	string[]	Exclude content from these HTML tags.
headers	Record<string, string>	Custom HTTP headers (cookies, user-agent, etc.).
waitFor	number	Extra delay in ms before fetching content, on top of smart-wait. Default: 0.
timeout	number	Request timeout in ms. Min: 1000, default: 60000, max: 300000.
mobile	boolean	Emulate a mobile device. Default: false.
maxAge	number	Use cached result if younger than this (ms). Default: 172800000 (2 days). Set 0 to bypass cache.
minAge	number	Cache-only mode. Returns cached data if it exists, 404 otherwise. Set 1 to accept any cached data.
storeInCache	boolean	Cache this scrape result.
actions	ActionOption[]	Browser actions to perform before scraping (wait, click, type, scroll, screenshot, etc.).
location	LocationConfig	Geolocation: { country: string, languages?: string[] }.
parsers	Array<string | object>	File parsers. Default: ["pdf"]. PDF parser supports mode ("fast", "auto", "ocr"), maxPages, pages, blocks, pageMarkers.
proxy	string	Proxy type: "basic", "stealth", "enhanced", "auto", or custom.
skipTlsVerification	boolean	Skip TLS cert verification. Default: true.
removeBase64Images	boolean	Strip base64 images from output.
blockAds	boolean	Block ads and cookie popups.
fastMode	boolean	Enable fast scraping mode.
lockdown	boolean	Serve only cached results.
checkPromptInjection	boolean	Scan content for prompt injection (adds 4 credits).
redactPII	boolean | RedactPIIOptions	Redact personally identifiable information.
profile	{ name: string, saveChanges?: boolean }	Persistent browser profile for storage across sessions.
domainTools	boolean	Return Alexandria tool contracts matched to the scraped domain.
toolDetail	"compact" | "summary" | "full"	Detail level for tool contracts.
integration	string	Integration identifier.
origin	string	Origin label for telemetry.

Interact

Why use it

After scraping a page, interact with it in a live browser session — execute code or natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

app.interact(jobId, args)

Example

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

const response = await app.interact(scrapeId, {
  prompt: "Search for iPhone 16 Pro Max",
});
console.log(response.output);

const result = await app.interact(scrapeId, {
  code: "document.title",
  language: "node",
});
console.log(result.result);

await app.stopInteraction(scrapeId);

Parameters

Parameter	Type	Description
jobId	string	The scrape job ID from a previous scrape’s metadata.scrapeId. Required.
code	string	Code to execute in the browser sandbox. Provide code or prompt. Max 100,000 chars.
prompt	string	Natural-language instruction for the browser agent. Provide code or prompt.
language	"python" | "node" | "bash"	Language for code execution. Default: "node".
timeout	number	Execution timeout in seconds. Min: 1, default: 30, max: 300.
origin	string	Origin label for telemetry.

Stopping an interaction

Call app.stopInteraction(jobId) to close the browser session and stop billing.

Notes

• Deprecated aliases: scrapeUrl → scrape, scrapeExecute → interact, stopInteractiveBrowser / deleteScrapeBrowser → stopInteraction. Always use the preferred names.
• Parameter naming: All parameters use camelCase.
• Package name: firecrawl (npm).
• Import: import { Firecrawl } from "firecrawl".
• Base URL: Defaults to https://api.firecrawl.dev. Override with apiUrl in the constructor for self-hosted instances.

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/v2/methods/scrape.ts
• firecrawl/apps/js-sdk/firecrawl/src/v2/methods/search.ts
• firecrawl-docs/api-reference/v2-openapi.json