Firecrawl Node SDK

The Firecrawl Node SDK is the JavaScript client for the Firecrawl API, the context API for AI agents. Search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and get back clean Markdown or structured data your agents can ship with.

Installation

To install the Firecrawl Node SDK, you can use npm:

npm install firecrawl

Usage

1. Get an API key from firecrawl.dev
2. Set the API key as an environment variable named FIRECRAWL_API_KEY or pass it as the apiKey option to the Firecrawl class.

Here's an example of how to use the SDK with error handling. It uses ES modules and top-level await, so save it as an .mjs file or set "type": "module" in your package.json:

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// Scrape a website
const scrapeResponse = await app.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html'],
});
console.log(scrapeResponse);

// Crawl a website (waiter)
const crawlResponse = await app.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: { formats: ['markdown', 'html'] },
  pollInterval: 2,
});
console.log(crawlResponse);

Request origin

Requests carry an origin tag that identifies the client. Pass the origin option to set it. Set origin on a single call to override it for that call, except for app.research methods, which always use the client origin.

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY', origin: '[email protected]' });

By default the tag is js-sdk@<version>. When the client is created by code inside an installed package (a wrapper library), the default is js-sdk.<package>@<version> instead, for example js-sdk.scope-name@<version>. Application code, REPLs and bundled files without node_modules in their path keep the plain default. Detection runs once when the client is created and sends only the package name, lowercased and sanitized into a slug. Set FIRECRAWL_DISABLE_CALLER_ORIGIN=1 to always use the plain default.

Scraping a URL

To scrape a single URL with error handling, use the scrape method. It takes the URL as a parameter and returns the scraped data.

const url = 'https://example.com';
const scrapedData = await app.scrape(url);

Video extraction

Use the video format on supported video URLs, including YouTube and TikTok. The returned video field is a signed URL to the extracted video file.

const doc = await app.scrape('https://www.youtube.com/watch?v=dQw4w9WgXcQ', {
  formats: ['video'],
});

console.log(doc.video);

Product extraction

Use the product format to deterministically pull a product (title, price, availability, variants) from product pages — the deterministic counterpart to the LLM-based json format.

const doc = await app.scrape('https://example.com/product/123', {
  formats: ['product'],
});

console.log(doc.product);

Menu extraction

Use the menu format to deterministically pull a merchant's menu (sections, items, prices, availability) from menu pages — the deterministic counterpart to the LLM-based json format.

const doc = await app.scrape('https://example.com/restaurant/menu', {
  formats: ['menu'],
});

console.log(doc.menu);

Parsing uploaded files

Use parse to upload a file (html, pdf, docx, etc.) as multipart form data and process it through the same parsing pipeline. Parse does not support browser-only formats/options like changeTracking, screenshot, branding, audio, video, actions, waitFor, location, or mobile.

const parsed = await app.parse(
  {
    data: '<html><body><h1>Hello parse</h1></body></html>',
    filename: 'upload.html',
    contentType: 'text/html',
  },
  {
    formats: ['markdown'],
  }
);

console.log(parsed.markdown);

To see which file formats parse accepts, call getParseFormats. Each entry has format, kind (for example, document or image), extensions, mimeTypes, and available (false when the format is not enabled on this deployment).

const formats = await app.getParseFormats();
console.log(formats.filter((f) => f.available).map((f) => f.format));

Crawling a Website

To crawl a website with error handling, use the crawl method. It takes the starting URL and optional parameters, including limits and per‑page scrapeOptions.

const crawlResponse = await app.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: { formats: ['markdown', 'html'] },
});

Asynchronous Crawl

To start an asynchronous crawl, use startCrawl. It returns a job ID you can poll with getCrawlStatus.

const start = await app.startCrawl('https://firecrawl.dev', {
  excludePaths: ['blog/*'],
  limit: 5,
});

Checking Crawl Status

To check the status of a crawl job with error handling, use the getCrawlStatus method. It takes the job ID as a parameter and returns the current status.

const status = await app.getCrawlStatus(start.id);

Extracting structured data from URLs

Use extract with a prompt and schema. Zod schemas are supported directly.

import { Firecrawl } from 'firecrawl';
import { z } from 'zod';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

const schema = z.object({
  title: z.string(),
});

const result = await app.extract({
  urls: ['https://firecrawl.dev'],
  prompt: 'Extract the page title',
  schema,
  showSources: true,
});

console.log(result.data);

Map a Website

Use map to generate a list of URLs from a website. Options let you customize the mapping process, including whether to utilize the sitemap or include subdomains.

const mapResult = await app.map('https://example.com');
console.log(mapResult);

Search

Use search to search the web and optionally scrape the results in the same call.

const results = await app.search('what is retrieval augmented generation?', { limit: 5 });
for (const result of results.web ?? []) {
  console.log(result.url, '-', result.title);
}

// Scrape every result as part of the search:
const scraped = await app.search('firecrawl changelog', {
  limit: 3,
  scrapeOptions: { formats: ['markdown'] },
});

Results are grouped by source: .web, .news and .images. Developer and gov category results are served inside .web.

Use categories to narrow web search to a kind of site:

const results = await app.search('nanopore basecalling accuracy', {
  categories: ['research'],
});

categories: ['research'] is a website filter, not the paper index. It restricts ordinary web search to roughly 14 academic domains (arxiv.org, pubmed.ncbi.nlm.nih.gov, nature.com, biorxiv.org, ...) and returns web page results. To search papers themselves, use research.searchPapers below.

Developer search

Use developerSearch for the dedicated developer index and its complete filter and response contract. Generic search(..., { categories: ['developer'] }) returns developer results inside .web in the ordinary web-result shape (first passage as the description) and does not accept these filters.

const evidence = await app.developerSearch('configure retry backoff', {
  repos: ['firecrawl/firecrawl'],
  types: ['issue', 'pull_request', 'readme'],
  passages: 3,
  language: 'TypeScript',
  license: 'MIT',
});

for (const result of evidence.results) {
  // Result kind is the id prefix; the API intentionally omits a type field.
  console.log(result.id, result.license);
  for (const passage of result.passages) {
    console.log(passage.text, passage.citation_url);
  }
}
console.log(evidence.repos); // indexed-status echoes for requested repos

developerSearch also supports sources, topic, minStars, maxStars, archived, fork, and skills: 'only'. Supplying both repos and sources OR-combines GitHub-backed and documentation results.

Government search

Use govSearch to search the Firecrawl Government Index: primary law and regulatory material from US federal, state, and local government sources, including statutes, regulations, codes, court opinions, and other government publications. Results come back in the ordinary web-result shape. Generic search('food labeling requirements', { categories: ['gov'] }) returns index results inside .web; like developer, it cannot be combined with other categories.

const law = await app.govSearch('food labeling requirements', {
  k: 5,
});

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

// State supreme court opinions that cite a federal statute:
const cases = await app.govSearch('qualified immunity', {
  courtType: 'state-supreme',
  cites: '42 U.S.C. § 1983',
});

Filters, all optional and combined with AND: jurisdiction ('us' for federal, or 'us-' plus a two-letter state or territory code, such as 'us-ca'), court (a CourtListener court id, such as 'scotus' or 'ca9'), courtType, cites (one printed citation or citation id, such as 'us:usc:42:1983'), and domain (one site, such as 'irs.gov'). Filters keep only pages the index has labeled, so a filtered search can leave out relevant pages, and no results does not mean none exist. Court labels are most complete for federal courts and case-law collections.

Research / paper search

Use app.research to search Firecrawl's research paper index: ~43M paper abstracts, roughly 90% biomedical and life sciences (PubMed, bioRxiv, medRxiv), plus arXiv for physics, mathematics and computer science.

// Search the paper index (semantic search over abstracts):
const papers = await app.research.searchPapers(
  'CRISPR base editing off-target effects in primary human T cells',
  { k: 10 },
);
for (const paper of papers.results) {
  console.log(paper.primaryId, '-', paper.title);
}

// Inspect one paper's metadata (accepts pmid:, pmcid:, doi: or arxiv: ids):
const paper = await app.research.getPaper('pmid:<id>');

// Read the passages inside a paper that answer a specific question:
const read = await app.research.getPaper('pmid:<id>', {
  query: 'what was the primary endpoint and the reported hazard ratio?',
  k: 4,
});

// Expand along the citation graph, re-ranked for your stated intent:
const related = await app.research.similarPapers('pmid:<id>', {
  intent: 'replication attempts in larger cohorts',
  k: 20,
});

app.research.searchGithub is deprecated. The research index GitHub endpoint stops responding after 2026-11-03. Use app.developerSearch instead: it searches GitHub issues, pull requests and readmes plus curated documentation sources, returns matched passages, and adds filters for repo, language, license and stars. It does not carry over the scores breakdown or the resultType: "web" fallback results. See the developer index docs.

Scrape-bound interactive browsing (v2)

Use a scrape job ID to keep interacting with the replayed browser context:

const doc = await app.scrape('https://example.com', {
  actions: [{ type: 'click', selector: 'a[href="/pricing"]' }],
});

const scrapeJobId = doc?.metadata?.scrapeId;
if (!scrapeJobId) throw new Error('Missing scrapeId');

const run = await app.interact(scrapeJobId, {
  code: 'console.log(await page.url())',
  language: 'node',
  timeout: 60,
});
console.log(run.stdout);

await app.stopInteraction(scrapeJobId);

Crawl a website with real‑time updates

To receive real‑time updates, start a crawl and attach a watcher.

const start = await app.startCrawl('https://firecrawl.dev', { excludePaths: ['blog/*'], limit: 5 });
const watch = app.watcher(start.id, { kind: 'crawl', pollInterval: 2 });

watch.on('document', (doc) => {
  console.log('DOC', doc);
});

watch.on('error', (err) => {
  console.error('ERR', err);
});

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

await watch.start();

Batch scraping multiple URLs

To batch scrape multiple URLs with error handling, use the batchScrape method.

const batchScrapeResponse = await app.batchScrape(['https://firecrawl.dev', 'https://docs.firecrawl.dev'], {
  formats: ['markdown', 'html'],
});

Asynchronous batch scrape

To start an asynchronous batch scrape, use startBatchScrape and poll with getBatchScrapeStatus.

const asyncBatchScrapeResult = await app.startBatchScrape(['https://firecrawl.dev', 'https://docs.firecrawl.dev'], {
  formats: ['markdown', 'html'],
});

Batch scrape with real‑time updates

To use batch scrape with real‑time updates, start the job and watch it using the watcher.

const start = await app.startBatchScrape(['https://firecrawl.dev', 'https://docs.firecrawl.dev'], { formats: ['markdown', 'html'] });
const watch = app.watcher(start.id, { kind: 'batch', pollInterval: 2 });

watch.on('document', (doc) => {
  console.log('DOC', doc);
});

watch.on('error', (err) => {
  console.error('ERR', err);
});

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

await watch.start();

v1 compatibility

The feature‑frozen v1 is still available under app.v1 with the original method names.

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// v1 methods (feature‑frozen)
const scrapeV1 = await app.v1.scrapeUrl('https://firecrawl.dev', { formats: ['markdown', 'html'] });
const crawlV1 = await app.v1.crawlUrl('https://firecrawl.dev', { limit: 100 });
const mapV1 = await app.v1.mapUrl('https://firecrawl.dev');

Error Handling

The SDK handles errors returned by the Firecrawl API and raises appropriate exceptions. If an error occurs during a request, an exception will be raised with a descriptive error message. The examples above demonstrate how to handle these errors using try/catch blocks.

License

The Firecrawl Node SDK is licensed under the MIT License. This means you are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the SDK, subject to the following conditions:

• The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Please note that while this SDK is MIT licensed, it is part of a larger project which may be under different licensing terms. Always refer to the license information in the root directory of the main project for overall licensing details.

Alexandria

With a matching API deployment, Search returns complete tool contracts in tools. domainTools: true adds domain matches to that same array. Find Tools walks the catalogue without executing the tools it returns.

const results = await firecrawl.search("podcast conversations about AI agents", {
  sources: ["web", "alexandria"],
  domainTools: true,
  limit: 2,
});
console.log(results.tools?.[0].options);

const catalogue = await firecrawl.findTools({ providers: ["particle"], limit: 2 });
const next = catalogue.items[0]?.next;
if (next) console.log(await firecrawl.scrape({ alexandria: next }));

Execute a selected contract with scrape({ alexandria, requestId }), where alexandria is one { provider, capability, options } call or an array of up to ten calls:

const requestId = crypto.randomUUID();
const result = await firecrawl.scrape({
  alexandria: {
    provider: "particle",
    capability: "podcasts/episodes/search",
    options: { semantic_search: "AI agents" },
  },
  requestId,
});
for (const item of result.alexandria) {
  if (item.error) console.error(item.error.code, item.error.message);
  else console.log(item.data);
}

Check each returned alexandria item's error before using its data. The result and execution errors expose requestId; reuse it with the identical payload for a retry. Automatic retries retain the same ID. Find Tools costs zero credits; provider execution uses its published price. A provider whose data terms have not been accepted rejects the call with a 403 whose SdkError carries code: "THIRD_PARTY_DATA_TERMS_REQUIRED" and a requiresAction: { type: "accept_terms", terms, version, url } pointing at the page where an organization admin can accept them.