Node.js SDK

Updated Feb 2026

The official Node.js SDK for Firecrawl. Works with JavaScript and TypeScript, supports all v2 API features, and provides both promise-based and WebSocket-based interfaces.

Package	@mendable/firecrawl-js
npm	npmjs.com/package/@mendable/firecrawl-js
API Versions	v1, v2
Source	github.com/mendableai/firecrawl

Installation

npm install @mendable/firecrawl-js

Or with other package managers:

# Yarn
yarn add @mendable/firecrawl-js

# pnpm
pnpm add @mendable/firecrawl-js

Initialization

import Firecrawl from '@mendable/firecrawl-js';

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

The API key can also be set via the FIRECRAWL_API_KEY environment variable.

---

Methods

scrape()

Scrapes a single URL and returns the content in the requested formats. See Scrape feature docs for full parameter details.

Signature:

firecrawl.scrape(url: string, options?: ScrapeOptions): Promise<ScrapeResult>

Parameters:

Parameter	Type	Required	Description
url	string	Yes	The URL to scrape
formats	string[]	No	Output formats: "markdown", "html", "rawHtml", "links", "screenshot", "json"

Example:

const result = await firecrawl.scrape("https://firecrawl.dev", {
  formats: ["markdown", "html"]
});
console.log(result.markdown);
console.log(result.html);

---

search()

Performs a web search and optionally scrapes the results. See Search feature docs for full parameter details.

Signature:

firecrawl.search(query: string, options?: SearchOptions): Promise<SearchResult>

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query string
limit	number	No	Maximum number of results (default: 5)
scrapeOptions	object	No	Options for scraping results, e.g., { formats: ["markdown"] }
sources	string	No	Result types: "web", "news", "images"
categories	string	No	Filter: "github", "research", "pdf"
location	string	No	Geographic targeting
tbs	string	No	Time filter: "qdr:h", "qdr:d", "qdr:w", "qdr:m"
timeout	number	No	Timeout in milliseconds

Example:

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

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

---

crawl()

Crawls a website starting from a URL. This is a blocking call that waits for the crawl to complete. Auto-paginates results by default. See Crawl feature docs for full parameter details.

Signature:

firecrawl.crawl(url: string, options?: CrawlOptions): Promise<CrawlResult>

Parameters:

Parameter	Type	Required	Description
url	string	Yes	Starting URL
limit	number	No	Maximum pages to crawl
pollInterval	number	No	Polling interval in seconds
timeout	number	No	Maximum wait time in seconds
scrapeOptions	object	No	Scrape settings, e.g., { formats: ["markdown"] }
sitemap	string	No	Sitemap mode: "only" to crawl sitemap URLs exclusively
excludePaths	string[]	No	URL paths to exclude from crawling

Example:

const job = await firecrawl.crawl("https://docs.firecrawl.dev", {
  limit: 5,
  pollInterval: 1,
  timeout: 120
});
console.log(job.status);
for (const doc of job.data) {
  console.log(doc.metadata.sourceURL);
}

Sitemap-only crawl:

const job = await firecrawl.crawl("https://docs.firecrawl.dev", {
  sitemap: "only",
  limit: 25
});
console.log(job.status, job.data.length);

---

startCrawl()

Initiates a non-blocking crawl and returns a job ID for status polling.

Signature:

firecrawl.startCrawl(url: string, options?: CrawlOptions): Promise<{ id: string }>

Example:

const { id } = await firecrawl.startCrawl("https://docs.firecrawl.dev", {
  limit: 10
});
console.log("Job ID:", id);

---

getCrawlStatus()

Retrieves the current status and results of a crawl job. Supports pagination control.

Signature:

firecrawl.getCrawlStatus(crawlId: string, options?: PaginationOptions): Promise<CrawlStatus>

Parameters:

Parameter	Type	Required	Description
crawlId	string	Yes	Job ID from startCrawl()
autoPaginate	boolean	No	Auto-fetch all pages (default: true)
maxPages	number	No	Maximum pages to fetch
maxResults	number	No	Maximum documents to collect
maxWaitTime	number	No	Maximum wait time in seconds

Examples:

// Single page fetch (no auto-pagination)
const status = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: false
});
console.log(status.status, status.completed, status.total);

// With limits
const limited = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15
});

---

cancelCrawl()

Cancels an active crawl job.

Signature:

firecrawl.cancelCrawl(crawlId: string): Promise<boolean>

Example:

const ok = await firecrawl.cancelCrawl("<crawl-id>");
console.log("Cancelled:", ok);

---

map()

Discovers all URLs on a website without scraping their content. See Map feature docs for full parameter details.

Signature:

firecrawl.map(url: string, options?: MapOptions): Promise<MapResult>

Parameters:

Parameter	Type	Required	Description
url	string	Yes	Target URL
limit	number	No	Maximum URLs to discover

Example:

const res = await firecrawl.map("https://firecrawl.dev", { limit: 10 });
for (const link of res.links) {
  console.log(link);
}

---

startBatchScrape()

Scrapes multiple URLs in a batch operation. Returns a job ID for status polling.

Signature:

firecrawl.startBatchScrape(urls: string[], options?: BatchScrapeOptions): Promise<{ id: string }>

Parameters:

Parameter	Type	Required	Description
urls	string[]	Yes	URLs to scrape
options	object	No	Nested options object with scrape settings like { formats: ["markdown"] }

Example:

const batchStart = await firecrawl.startBatchScrape([
  "https://docs.firecrawl.dev",
  "https://firecrawl.dev",
], {
  options: { formats: ["markdown"] }
});
console.log("Batch Job ID:", batchStart.id);

---

getBatchScrapeStatus()

Checks the status of a batch scrape job. Supports pagination control.

Signature:

firecrawl.getBatchScrapeStatus(jobId: string, options?: PaginationOptions): Promise<BatchScrapeStatus>

Parameters:

Parameter	Type	Required	Description
jobId	string	Yes	Job ID from startBatchScrape()
autoPaginate	boolean	No	Auto-fetch all pages (default: true)
maxPages	number	No	Maximum pages to fetch
maxResults	number	No	Maximum documents to collect
maxWaitTime	number	No	Maximum wait time in seconds

Example:

const batchStatus = await firecrawl.getBatchScrapeStatus(batchStart.id, {
  autoPaginate: false
});
console.log(batchStatus.status, batchStatus.completed, batchStatus.total);

---

extract()

Extracts structured data from one or more URLs using a schema or natural language prompt. Supports wildcard URL patterns. See Extract feature docs for full parameter details.

Signature:

firecrawl.extract(options: ExtractOptions): Promise<ExtractResult>

Parameters:

Parameter	Type	Required	Description
urls	string[]	Yes	URLs to extract from (supports wildcards like example.com/*)
prompt	string	No	Natural language description of the data to extract
schema	object	No	JSON Schema defining the output structure
enableWebSearch	boolean	No	Allow extraction to follow external links

Example:

const result = await firecrawl.extract({
  urls: ["https://firecrawl.dev/*"],
  prompt: "Extract the company name, description, and pricing plans",
  schema: {
    type: "object",
    properties: {
      company: { type: "string" },
      description: { type: "string" },
      pricing_plans: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            price: { type: "string" }
          }
        }
      }
    }
  }
});
console.log(result);

---

agent()

Autonomous web data gathering agent. Searches, navigates, and extracts data without requiring specific URLs. See Agent feature docs for full parameter details.

Signature:

firecrawl.agent(options: AgentOptions): Promise<AgentResult>

Parameters:

Parameter	Type	Required	Description
prompt	string	Yes	Natural language description of data to gather (max 10,000 chars)
model	string	No	"spark-1-mini" (default) or "spark-1-pro"
urls	string[]	No	Optional URLs to focus extraction scope
schema	object	No	JSON Schema or Zod schema for structured output
maxCredits	number	No	Credit spending limit (default: 2,500)

Example with Zod schema:

import { z } from 'zod';

const result = await firecrawl.agent({
  prompt: "Find the founders of Firecrawl",
  model: "spark-1-mini",
  maxCredits: 100,
  schema: z.object({
    founders: z.array(z.object({
      name: z.string(),
      role: z.string().optional()
    }))
  })
});
console.log(result);

---

watcher()

Subscribes to real-time crawl updates via WebSocket with HTTP fallback.

Signature:

firecrawl.watcher(jobId: string, options?: WatcherOptions): Watcher

Parameters:

Parameter	Type	Required	Description
jobId	string	Yes	Job ID from startCrawl()
kind	string	No	Job type, e.g., "crawl"
pollInterval	number	No	Polling interval in seconds
timeout	number	No	Maximum wait time in seconds

Events:

Event	Description
"document"	Fired for each scraped document
"error"	Fired on errors
"done"	Fired when the job completes

Example:

const { id } = await firecrawl.startCrawl("https://mendable.ai", {
  excludePaths: ["blog/*"],
  limit: 5
});

const watcher = firecrawl.watcher(id, {
  kind: "crawl",
  pollInterval: 2,
  timeout: 120
});

watcher.on("document", (doc) => {
  console.log("DOC", doc.metadata?.sourceURL);
});

watcher.on("error", (err) => {
  console.error("ERR", err?.error || err);
});

watcher.on("done", (state) => {
  console.log("DONE", state.status);
});

await watcher.start();

---

Browser Methods

Firecrawl provides cloud browser sessions that you can control programmatically. See Browser feature docs for full details.

browser()

Creates a cloud browser session.

Parameters:

Parameter	Type	Required	Description
ttl	number	No	Session time-to-live in seconds
profile	object	No	Browser profile with name and saveChanges keys

Example:

const session = await firecrawl.browser({ ttl: 300 });
console.log(session.id);           // session ID
console.log(session.cdpUrl);       // wss://cdp-proxy.firecrawl.dev/...
console.log(session.liveViewUrl);  // live monitoring URL

With profile:

const session = await firecrawl.browser({
  ttl: 300,
  profile: {
    name: "my-profile",
    saveChanges: true
  }
});

browserExecute()

Executes code within a browser session.

Parameters:

Parameter	Type	Required	Description
sessionId	string	Yes	Session ID
code	string	Yes	Code to execute
language	string	No	"python", "node", or "bash"

Examples:

// Python (default)
const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://news.ycombinator.com")\nprint(await page.title())',
});
console.log(result.result);

// JavaScript
const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://example.com"); console.log(await page.title());',
  language: "node",
});

// Bash
const result = await firecrawl.browserExecute(session.id, {
  code: "agent-browser open https://example.com && agent-browser snapshot",
  language: "bash",
});

listBrowsers()

Lists active browser sessions.

const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

deleteBrowser()

Closes a browser session.

await firecrawl.deleteBrowser(session.id);

Playwright CDP Integration

Connect to a Firecrawl browser session using Playwright:

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

---

Pagination Options

Default behavior: the SDK auto-paginates and aggregates all documents. Control pagination with these options on getCrawlStatus() and getBatchScrapeStatus():

Option	Type	Default	Description
autoPaginate	boolean	true	Automatically fetch all pages
maxPages	number	--	Stop after this many pages
maxResults	number	--	Stop after collecting this many documents
maxWaitTime	number	--	Stop after this many seconds

---

Error Handling

The SDK raises appropriate exceptions for API errors. Use try/catch blocks to handle failures:

try {
  const result = await firecrawl.scrape("https://example.com", {
    formats: ["markdown"]
  });
} catch (error) {
  console.error("Firecrawl error:", error.message);
}

Common error scenarios:

Scenario	Cause
Invalid API key	Key is missing, expired, or malformed
Rate limit exceeded	Too many requests in a short period
URL not reachable	Target URL is down or blocked
Timeout	Operation exceeded the configured timeout
Credit limit reached	Account or job credit limit exceeded

---

TypeScript Support

The SDK is written in TypeScript and provides full type definitions out of the box. All method signatures, options, and response types are strongly typed.

import Firecrawl from '@mendable/firecrawl-js';

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

// Type-safe options and responses
const result = await firecrawl.scrape("https://example.com", {
  formats: ["markdown", "html"]  // string literal union type
});

// result.markdown and result.html are typed
console.log(result.markdown);

---

Related Pages

• SDKs Overview -- Compare all available SDKs
• Python SDK -- Python SDK reference
• CLI Reference -- Command-line interface
• Scrape -- Single-page extraction details
• Crawl -- Multi-page crawling details
• Search -- Web search details
• Extract -- Structured data extraction
• Agent -- Autonomous data gathering