JavaScript SDK - Firecrawl

The Firecrawl JavaScript SDK provides a typed interface for scraping, crawling, and extracting structured data from websites. It supports both ESM and CommonJS, and automatically handles polling for async operations.

Installation

npm install @mendable/firecrawl-js

Quick Start

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

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

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

Authentication

Get your API key from firecrawl.dev and set it as an environment variable or pass it directly:

// Option 1: Environment variable
process.env.FIRECRAWL_API_KEY = 'fc-YOUR_API_KEY';
const app = new Firecrawl();

// Option 2: Direct parameter
const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

Scraping

Basic Scrape

Scrape a single URL and get content in various formats:

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

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

// Get markdown and HTML
const doc = await app.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html']
});

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

Structured Data Extraction

Extract structured data using Zod schemas:

import Firecrawl from '@mendable/firecrawl-js';
import { z } from 'zod';

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

const schema = z.object({
  companyMission: z.string(),
  isOpenSource: z.boolean(),
  isInYC: z.boolean()
});

const doc = await app.scrape('https://firecrawl.dev', {
  formats: [{ type: 'json', schema }]
});

console.log(doc.json);
// { companyMission: "Turn websites into LLM-ready data", isOpenSource: true, isInYC: true }

Extract with Prompt (No Schema)

const doc = await app.scrape('https://firecrawl.dev', {
  formats: [{
    type: 'json',
    prompt: 'Extract the company mission'
  }]
});

Additional Formats

// Get screenshot
const doc = await app.scrape('https://firecrawl.dev', {
  formats: ['screenshot']
});
console.log(doc.screenshot); // Base64 encoded image

// Get branding information
const doc = await app.scrape('https://firecrawl.dev', {
  formats: ['branding']
});
console.log(doc.branding); // { colors: {...}, fonts: [...], typography: {...} }

// Get all links
const doc = await app.scrape('https://firecrawl.dev', {
  formats: ['links']
});
console.log(doc.links);

Actions (Interact Before Scraping)

Perform actions before extracting content:

const doc = await app.scrape('https://example.com/login', {
  formats: ['markdown'],
  actions: [
    { type: 'write', text: 'user@example.com' },
    { type: 'press', key: 'Tab' },
    { type: 'write', text: 'password' },
    { type: 'click', selector: 'button[type="submit"]' },
    { type: 'wait', milliseconds: 2000 },
    { type: 'screenshot' }
  ]
});

Crawling

Basic Crawl (Auto-Wait)

Crawl a website and automatically wait for completion:

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

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

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

for (const doc of result.data) {
  console.log(doc.metadata.sourceURL);
  console.log(doc.markdown.substring(0, 100));
}

Async Crawl (Manual Polling)

Start a crawl and poll manually:

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

console.log(`Crawl started with ID: ${start.id}`);

// Check status later
const status = await app.getCrawlStatus(start.id);
console.log(`Status: ${status.status}`);
console.log(`Completed: ${status.completed}/${status.total}`);

Cancel a Crawl

const cancelled = await app.cancelCrawl(start.id);
console.log(cancelled);

Advanced Crawl Options

const result = await app.crawl('https://firecrawl.dev', {
  limit: 50,
  maxDiscoveryDepth: 3,
  excludePaths: ['blog/*', 'admin/*'],
  includePaths: ['docs/*'],
  allowBackwardLinks: true,
  scrapeOptions: {
    formats: ['markdown', 'html'],
    onlyMainContent: true
  }
});

Real-Time Updates with Watcher

Watch crawl progress in real-time:

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

const watch = app.watcher(start.id, {
  kind: 'crawl',
  pollInterval: 2
});

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

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

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

await watch.start();

Agent

Use the AI agent to autonomously gather data from the web:

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

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

// Simple prompt-based extraction
const result = await app.agent({
  prompt: 'Find the founders of Stripe'
});
console.log(result.data);

Agent with Schema

import { z } from 'zod';

const schema = z.object({
  founders: z.array(z.object({
    name: z.string().describe('Full name of the founder'),
    role: z.string().optional().describe('Role or position')
  }))
});

const result = await app.agent({
  prompt: 'Find the founders of Firecrawl',
  schema
});

console.log(result.data);
// {
//   founders: [
//     { name: "Eric Ciarla", role: "Co-founder" },
//     { name: "Nicolas Camara", role: "Co-founder" },
//     { name: "Caleb Peffer", role: "Co-founder" }
//   ]
// }

Agent with URLs

Focus the agent on specific pages:

const result = await app.agent({
  urls: ['https://docs.firecrawl.dev', 'https://firecrawl.dev/pricing'],
  prompt: 'Compare the features and pricing information'
});

Model Selection

// Use the pro model for complex tasks
const result = await app.agent({
  prompt: 'Compare enterprise features across Firecrawl, Apify, and ScrapingBee',
  model: 'spark-1-pro'
});

// Default is spark-1-mini (60% cheaper)
const result = await app.agent({
  prompt: 'What is Firecrawl?',
  model: 'spark-1-mini'  // or omit for default
});

Map

Generate a list of all URLs on a website:

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

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

const mapResult = await app.map('https://firecrawl.dev');
console.log(mapResult.links);

Map with Search

// Find URLs related to a specific topic
const mapResult = await app.map('https://firecrawl.dev', {
  search: 'pricing'
});
// Returns URLs ordered by relevance to "pricing"

Search

Search the web and optionally scrape results:

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

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

const results = await app.search('best web scraping tools 2024', {
  limit: 10
});

results.data.web.forEach(result => {
  console.log(`${result.title}: ${result.url}`);
});

Search with Content Scraping

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

Batch Scraping

Scrape multiple URLs in parallel:

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

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

// Auto-wait for completion
const result = await app.batchScrape(
  ['https://firecrawl.dev', 'https://docs.firecrawl.dev'],
  { formats: ['markdown'] }
);

for (const doc of result.data) {
  console.log(doc.metadata.sourceURL);
}

Async Batch Scrape

// Start batch scrape
const start = await app.startBatchScrape(
  ['https://firecrawl.dev', 'https://docs.firecrawl.dev'],
  { formats: ['markdown'] }
);

// Check status later
const status = await app.getBatchScrapeStatus(start.id);
console.log(`Completed: ${status.completed}/${status.total}`);

Batch Scrape with Real-Time Updates

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

const watch = app.watcher(start.id, {
  kind: 'batch',
  pollInterval: 2
});

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

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

await watch.start();

Extract (Deprecated)

The Extract endpoint is deprecated. Use the Agent feature instead for better performance and reliability.

import { z } from 'zod';

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

v1 Compatibility

Legacy v1 API is available under app.v1:

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

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 throws errors for API failures:

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

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

try {
  const result = await app.scrape('https://example.com');
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Invalid API key');
  } else if (error.response?.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Error:', error.message);
  }
}

Configuration

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

const app = new Firecrawl({
  apiKey: 'fc-YOUR_API_KEY',
  apiUrl: 'https://api.firecrawl.dev',  // Default
  timeoutMs: 300000,                     // Request timeout (5 min default)
  maxRetries: 3,                         // Max retry attempts
  backoffFactor: 0.5                     // Exponential backoff factor
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import Firecrawl, {
  type Document,
  type ScrapeOptions,
  type CrawlOptions,
  type AgentOptions
} from '@mendable/firecrawl-js';

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

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

Requirements

Node.js 22.0.0 or later

Documentation Index

​Installation

​Quick Start

​Authentication

​Scraping

​Basic Scrape

​Structured Data Extraction

​Extract with Prompt (No Schema)

​Additional Formats

​Actions (Interact Before Scraping)

​Crawling

​Basic Crawl (Auto-Wait)

​Async Crawl (Manual Polling)

​Cancel a Crawl

​Advanced Crawl Options

​Real-Time Updates with Watcher

​Agent

​Agent with Schema

​Agent with URLs

​Model Selection

​Map

​Map with Search

​Search

​Search with Content Scraping

​Batch Scraping

​Async Batch Scrape

​Batch Scrape with Real-Time Updates

​Extract (Deprecated)

​v1 Compatibility

​Error Handling

​Configuration

​TypeScript Support

​Requirements

​Resources

Installation

Quick Start

Authentication

Scraping

Basic Scrape

Structured Data Extraction

Extract with Prompt (No Schema)

Additional Formats

Actions (Interact Before Scraping)

Crawling

Basic Crawl (Auto-Wait)

Async Crawl (Manual Polling)

Cancel a Crawl

Advanced Crawl Options

Real-Time Updates with Watcher

Agent

Agent with Schema

Agent with URLs

Model Selection

Map

Map with Search

Search

Search with Content Scraping

Batch Scraping

Async Batch Scrape

Batch Scrape with Real-Time Updates

Extract (Deprecated)

v1 Compatibility

Error Handling

Configuration

TypeScript Support

Requirements

Resources