Migration Guide: v1 to v2

Updated Feb 2026

This guide covers everything you need to upgrade your Firecrawl integration from v1 to v2. The v2 API introduces faster defaults, cleaner method names, new formats, and smart crawling with prompts.

Key Improvements in v2

Improvement	Details
Faster by default	Requests are cached with `maxAge` defaulting to 2 days. Sensible defaults like `blockAds`, `skipTlsVerification`, and `removeBase64Images` are enabled.
New summary format	Specify `"summary"` as a format to receive a concise summary of page content.
Updated JSON extraction	JSON extraction uses an object format: `{ type: "json", prompt, schema }`. The old `"extract"` format has been renamed to `"json"`.
Enhanced screenshot options	Use the object form: `{ type: "screenshot", fullPage, quality, viewport }`.
New search sources	Search across `"news"` and `"images"` in addition to web results via the `sources` parameter.
Smart crawling with prompts	Pass a natural-language `prompt` to crawl and the system derives paths/limits automatically.

Quick Migration Checklist

[ ] Replace v1 client initialization with v2 clients
[ ] Update method names (see tables below)
[ ] Update formats ("extract" becomes { type: "json" }, etc.)
[ ] Adopt standardized async flows (startCrawl + getCrawlStatus)
[ ] Update crawl options (maxDepth becomes maxDiscoveryDepth, etc.)
[ ] Test with /crawl/params-preview if using prompts

Client Initialization

JS/TS v2Python v2API v2

javascript

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

// v2 client
const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

python

from firecrawl import Firecrawl

# v2 client
firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')

bash

# Use v2 base URL
https://api.firecrawl.dev/v2/

Method Name Changes

JS/TS SDK

Scrape, Search, and Map

v1 (`FirecrawlApp`)	v2 (`Firecrawl`)
`scrapeUrl(url, ...)`	`scrape(url, options?)`
`search(query, ...)`	`search(query, options?)`
`mapUrl(url, ...)`	`map(url, options?)`

Crawling

v1	v2
`crawlUrl(url, ...)`	`crawl(url, options?)` (waiter)
`asyncCrawlUrl(url, ...)`	`startCrawl(url, options?)`
`checkCrawlStatus(id, ...)`	`getCrawlStatus(id)`
`cancelCrawl(id)`	`cancelCrawl(id)`
`checkCrawlErrors(id)`	`getCrawlErrors(id)`

Batch Scraping

v1	v2
`batchScrapeUrls(urls, ...)`	`batchScrape(urls, opts?)` (waiter)
`asyncBatchScrapeUrls(urls, ...)`	`startBatchScrape(urls, opts?)`
`checkBatchScrapeStatus(id, ...)`	`getBatchScrapeStatus(id)`
`checkBatchScrapeErrors(id)`	`getBatchScrapeErrors(id)`

Extraction

v1	v2
`extract(urls?, params?)`	`extract(args)`
`asyncExtract(urls, params?)`	`startExtract(args)`
`getExtractStatus(id)`	`getExtractStatus(id)`

Removed / Changed

v1	v2
`generateLLMsText(...)`	(removed from v2 SDK)
`checkGenerateLLMsTextStatus(id)`	(removed from v2 SDK)
`crawlUrlAndWatch(...)`	`watcher(jobId, ...)`
`batchScrapeUrlsAndWatch(...)`	`watcher(jobId, ...)`

Python SDK (sync)

Scrape, Search, and Map

v1	v2
`scrape_url(...)`	`scrape(...)`
`search(...)`	`search(...)`
`map_url(...)`	`map(...)`

Crawling

v1	v2
`crawl_url(...)`	`crawl(...)` (waiter)
`async_crawl_url(...)`	`start_crawl(...)`
`check_crawl_status(...)`	`get_crawl_status(...)`
`cancel_crawl(...)`	`cancel_crawl(...)`

Batch Scraping

v1	v2
`batch_scrape_urls(...)`	`batch_scrape(...)` (waiter)
`async_batch_scrape_urls(...)`	`start_batch_scrape(...)`
`get_batch_scrape_status(...)`	`get_batch_scrape_status(...)`
`get_batch_scrape_errors(...)`	`get_batch_scrape_errors(...)`

Extraction

v1	v2
`extract(...)`	`extract(...)`
`start_extract(...)`	`start_extract(...)`
`get_extract_status(...)`	`get_extract_status(...)`

Removed / Changed

v1	v2
`generate_llms_text(...)`	(removed from v2 SDK)
`get_generate_llms_text_status(...)`	(removed from v2 SDK)
`watch_crawl(...)`	`watcher(job_id, ...)`

Python SDK (async)

AsyncFirecrawl mirrors the same methods as the sync client -- all methods are awaitable.

Format Changes

String Formats

Use string formats for basic output types:

javascript

// v2 string formats
const formats = ["markdown", "html", "rawHtml", "links", "summary", "images"];

New in v2

The "summary" and "images" formats are new in v2.

JSON Format (Breaking Change)

The old "extract" format name has been renamed to a JSON object format:

v1 (Old)v2 (New)

javascript

// v1 -- string format name
const formats = ["extract"];
const extract = { schema: mySchema, prompt: "Extract the data" };

javascript

// v2 -- object format
const formats = [{
  type: "json",
  prompt: "Extract the company mission from the page.",
  schema: {
    mission: { type: "string" }
  }
}];

const doc = firecrawl.scrape(url, { formats });

Screenshot Format (Breaking Change)

Screenshots now use an object format for full control:

v1 (Old)v2 (New)

javascript

// v1 -- string format
const formats = ["screenshot@fullPage"];

javascript

// v2 -- object format with options
const formats = [{
  type: "screenshot",
  fullPage: true,
  quality: 80,
  viewport: { width: 1280, height: 800 }
}];

const doc = firecrawl.scrape(url, { formats });

PDF Parsing

javascript

// v1
const options = { parsePDF: true };

// v2
const options = { parsers: [{ type: "pdf" }] };
// or shorthand:
const options = { parsers: ["pdf"] };

Crawl Options Changes

Options Mapping

v1 Parameter	v2 Parameter	Notes
`allowBackwardCrawling`	`crawlEntireDomain`	Renamed. Controls whether the crawler follows links outside the starting path.
`maxDepth`	`maxDiscoveryDepth`	Renamed. Maximum depth of link discovery from the starting URL.
`ignoreSitemap` (boolean)	`sitemap` (string)	Changed from boolean to enum: `"only"`, `"skip"`, or `"include"`.
(none)	`prompt`	New in v2. Pass natural language to auto-derive crawl parameters.

Crawl with Prompt (New in v2)

v2 introduces smart crawling where you can describe what you want in natural language:

Node.jsPython

javascript

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

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

// Smart crawl with a prompt
const result = await firecrawl.crawl('https://docs.firecrawl.dev', {
  prompt: 'Extract all documentation pages and blog posts'
});

python

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')

# Smart crawl with a prompt
result = firecrawl.crawl('https://docs.firecrawl.dev',
    prompt='Extract all documentation pages and blog posts'
)

Crawl Params Preview

Before running a prompt-based crawl, you can preview what parameters will be derived:

Node.jsPythoncURL

javascript

const params = await firecrawl.crawlParamsPreview(
  'https://docs.firecrawl.dev',
  'Extract docs and blog'
);
console.log(params);
// Shows derived: includePaths, excludePaths, limit, etc.

python

params = firecrawl.crawl_params_preview(
    'https://docs.firecrawl.dev',
    'Extract docs and blog'
)
print(params)

bash

curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "prompt": "Extract docs and blog"
    }'

Async Flow Changes

v2 standardizes how asynchronous operations work across all job types:

Pattern: Start + Poll

javascript

// v2 pattern for all async operations
// 1. Start the job
const job = await firecrawl.startCrawl(url, options);

// 2. Poll for status
const status = await firecrawl.getCrawlStatus(job.id);

Pattern: Waiter (Auto-Poll)

javascript

// v2 waiter methods handle polling for you
const result = await firecrawl.crawl(url, options);
// Returns when the job is complete

Unified Watcher

The v1 methods crawlUrlAndWatch and batchScrapeUrlsAndWatch are replaced by a single watcher method:

javascript

// v1
const watcher = firecrawl.crawlUrlAndWatch(url, options);

// v2
const job = await firecrawl.startCrawl(url, options);
const watcher = firecrawl.watcher(job.id, {
  onEvent: (event) => console.log(event)
});

API Endpoint Changes

Operation	v1 Endpoint	v2 Endpoint
Scrape	`POST /v1/scrape`	`POST /v2/scrape`
Crawl	`POST /v1/crawl`	`POST /v2/crawl`
Crawl Status	`GET /v1/crawl/{id}`	`GET /v2/crawl/{id}`
Map	`POST /v1/map`	`POST /v2/map`
Search	`POST /v1/search`	`POST /v2/search`
Batch Scrape	`POST /v1/batch/scrape`	`POST /v2/batch/scrape`
Extract	`POST /v1/extract`	`POST /v2/extract`
Crawl Params Preview	(none)	`POST /v2/crawl/params-preview`

Breaking Changes Summary

Change	Impact	Action Required
Client class renamed	`FirecrawlApp` becomes `Firecrawl`	Update import and instantiation
Method names simplified	`scrapeUrl` becomes `scrape`, etc.	Find and replace method calls
JSON format object	`"extract"` string becomes `{ type: "json" }`	Update format arrays
Screenshot format object	`"screenshot@fullPage"` becomes `{ type: "screenshot", fullPage: true }`	Update format arrays
PDF parsing syntax	`parsePDF: true` becomes `parsers: ["pdf"]`	Update scrape options
Crawl options renamed	`maxDepth` becomes `maxDiscoveryDepth`	Update crawl option keys
Sitemap option type	`ignoreSitemap: true` becomes `sitemap: "skip"`	Update from boolean to string enum
LLMs text generation	`generateLLMsText` removed	Remove calls or find alternative
Watcher pattern	Per-operation watchers become unified `watcher(jobId)`	Update watcher usage

Rate Limits -- Per-plan rate limits for v2 endpoints
Billing & Plans -- Credit costs for v2 endpoints
Webhooks Overview -- Webhook support in v2
Scrape -- v2 Scrape endpoint documentation

Migration Guide: v1 to v2 ​

Key Improvements in v2 ​

Quick Migration Checklist ​

Client Initialization ​

Method Name Changes ​

JS/TS SDK ​

Scrape, Search, and Map ​

Crawling ​

Batch Scraping ​

Extraction ​

Removed / Changed ​

Python SDK (sync) ​

Scrape, Search, and Map ​

Crawling ​

Batch Scraping ​

Extraction ​

Removed / Changed ​

Python SDK (async) ​

Format Changes ​

String Formats ​

JSON Format (Breaking Change) ​

Screenshot Format (Breaking Change) ​

PDF Parsing ​

Crawl Options Changes ​

Options Mapping ​

Crawl with Prompt (New in v2) ​

Crawl Params Preview ​

Async Flow Changes ​

Pattern: Start + Poll ​

Pattern: Waiter (Auto-Poll) ​

Unified Watcher ​

API Endpoint Changes ​

Breaking Changes Summary ​

Related Pages ​

Migration Guide: v1 to v2

Key Improvements in v2

Quick Migration Checklist

Client Initialization

Method Name Changes

JS/TS SDK

Scrape, Search, and Map

Crawling

Batch Scraping

Extraction

Removed / Changed

Python SDK (sync)

Scrape, Search, and Map

Crawling

Batch Scraping

Extraction

Removed / Changed

Python SDK (async)

Format Changes

String Formats

JSON Format (Breaking Change)

Screenshot Format (Breaking Change)

PDF Parsing

Crawl Options Changes

Options Mapping

Crawl with Prompt (New in v2)

Crawl Params Preview

Async Flow Changes

Pattern: Start + Poll

Pattern: Waiter (Auto-Poll)

Unified Watcher

API Endpoint Changes

Breaking Changes Summary

Related Pages