Firecrawl Node.js Agent Quickstart

This is the canonical quickstart for external agents integrating with Firecrawl using the official Node.js/TypeScript SDK. 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" });

Constructor options:

Option	Type	Default	Description
`apiKey`	`string \| null`	`FIRECRAWL_API_KEY` env var	API key. Omit for keyless free tier (rate-limited per IP).
`apiUrl`	`string \| null`	`https://api.firecrawl.dev`	Base URL. Falls back to `FIRECRAWL_API_URL` env var.
`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 search results grouped by source type, optionally with scraped content.
scrape — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats.
interact — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox.

Search

Why use it

Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL.

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.url, item.markdown?.slice(0, 200));
}

Parameters

All parameters are optional unless noted.

Parameter	Type	Description
`query`	`string`	Required (positional). The search query.
`sources`	`Array<"web" \| "news" \| "images" \| { type: ... }>`	Source types to search.
`categories`	`Array<"github" \| "research" \| "pdf" \| "developer" \| { type: ... }>`	Filter by category.
`includeDomains`	`string[]`	Restrict results to these domains. Mutually exclusive with `excludeDomains`.
`excludeDomains`	`string[]`	Exclude results from these domains.
`limit`	`number`	Max results to return.
`tbs`	`string`	Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week).
`location`	`string`	Geographic location for results.
`ignoreInvalidURLs`	`boolean`	Exclude URLs invalid for other Firecrawl endpoints.
`timeout`	`number`	Timeout in milliseconds.
`highlights`	`boolean`	Generate query-relevant highlights.
`scrapeOptions`	`ScrapeOptions`	Options applied when scraping each result. See Scrape parameters.
`enterprise`	`Array<"default" \| "anon" \| "zdr">`	Enterprise zero data retention options.
`threatProtection`	`ThreatProtectionOptions`	Per-request threat protection override.
`integration`	`string`	Integration identifier.
`origin`	`string`	Request origin tag.

Scrape

Why use it

Fetch and extract content from a single URL. Use when you have a specific page to read.

Preferred SDK method

client.scrape(url, options?)

Example

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

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

Parameters

All parameters are optional unless noted.

Parameter	Type	Description
`url`	`string`	Required (positional). The URL to scrape.
`formats`	`FormatOption[]`	Output formats. String values: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object variants: `{ type: "json", schema?, prompt? }`, `{ type: "screenshot", fullPage?, quality?, viewport? }`, `{ type: "changeTracking", modes, schema?, prompt?, tag? }`, `{ type: "attributes", selectors }`, `{ type: "question", question }`, `{ type: "highlights", query }`.
`headers`	`Record<string, string>`	Custom HTTP headers to send with the request.
`includeTags`	`string[]`	HTML tags to include exclusively.
`excludeTags`	`string[]`	HTML tags to exclude.
`onlyMainContent`	`boolean`	Only return main content, excluding navbars/footers.
`timeout`	`number`	Timeout in milliseconds.
`waitFor`	`number`	Delay in ms before fetching content.
`mobile`	`boolean`	Emulate a mobile device.
`parsers`	`Array<string \| { type: "pdf", mode?, maxPages? }>`	File processing parsers. PDF modes: `"fast"`, `"auto"`, `"ocr"`.
`actions`	`ActionOption[]`	Browser actions to perform before scraping. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`.
`location`	`{ country?: string, languages?: string[] }`	Geolocation for proxy routing.
`skipTlsVerification`	`boolean`	Skip TLS certificate verification.
`removeBase64Images`	`boolean`	Remove base64 images from output.
`fastMode`	`boolean`	Faster scraping with reduced accuracy.
`useMock`	`string`	Use a mock response.
`blockAds`	`boolean`	Block ads and cookie popups.
`proxy`	`"basic" \| "stealth" \| "enhanced" \| "auto" \| string`	Proxy mode.
`maxAge`	`number`	Use cached result if younger than this (ms).
`minAge`	`number`	Minimum cache age (ms). Set to 1 for any cached data.
`storeInCache`	`boolean`	Whether to cache the result.
`lockdown`	`boolean`	Serve only cached results. No outbound request.
`redactPII`	`boolean \| { mode?, entities?, replaceStyle? }`	Redact personally identifiable information. Modes: `"accurate"`, `"aggressive"`, `"fast"`.
`threatProtection`	`ThreatProtectionOptions`	Per-request threat protection override.
`auditMetadata`	`{ username: string }`	User attribution for SIEM logging.
`profile`	`{ name: string, saveChanges?: boolean }`	Persistent browser storage profile.
`integration`	`string`	Integration identifier.
`origin`	`string`	Request origin tag.

Interact

Why use it

Execute code or natural-language prompts in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data.

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.querySelector('button.load-more')?.click();",
  language: "node",
  timeout: 30,
});

console.log(result.stdout);

Parameters

Parameter	Type	Description
`jobId`	`string`	Required (positional). The scrape job ID from a prior scrape.
`code`	`string`	Code to execute in the browser sandbox. Required if `prompt` is not provided.
`prompt`	`string`	Natural-language instruction for the browser agent. Required if `code` is not provided.
`language`	`"python" \| "node" \| "bash"`	Runtime language for `code`.
`timeout`	`number`	Execution timeout in seconds (1-300).
`origin`	`string`	Request origin tag.

client.stopInteraction(jobId)

Stops the interactive browser session and returns billing info.

Notes

Naming style: All parameters use camelCase.
Deprecated aliases:
- scrapeUrl() → use scrape() instead.
- scrapeExecute() → use interact() instead.
- stopInteractiveBrowser() and deleteScrapeBrowser() → use stopInteraction() instead.
Async client: The SDK is async by default (all methods return Promises).
Zod schemas: The json format accepts Zod schemas in addition to plain JSON Schema objects for the schema field.

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

LLM SDKs and Frameworks

Agent Endpoint

Agent Quickstarts

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

​Related method

​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

Related method

Notes

Source Of Truth