Migration
Migrate from another API (/v2)

Migrate from another API (/v2)

The /v2 paths accept the request and response shapes of the Firecrawl v2 API. If your code calls that API through its official Node (@mendable/firecrawl-js) or Python (firecrawl-py) client, you can point the client at SuperScraper, keep your call sites, and move to the /v1 operations at your own pace.

⚠️

The /v2 paths are a migration door. They exist so an existing integration can switch with a base URL and key change. New work should call the /v1 operations directly: they expose every option we support and return our full response (completeness, provenance, cache and cascade details).

Point the client at SuperScraper

import Firecrawl from "@mendable/firecrawl-js";
 
const client = new Firecrawl({
  apiKey: process.env.SUPERSCRAPER_KEY,
  apiUrl: "https://api.superscraper.dev",
});
 
const doc = await client.scrape("https://example.com", { formats: ["markdown", "links"] });
import os
from firecrawl import Firecrawl
 
client = Firecrawl(api_key=os.environ["SUPERSCRAPER_KEY"], api_url="https://api.superscraper.dev")
doc = client.scrape("https://example.com", formats=["markdown", "links"])

Tested client versions: @mendable/firecrawl-js 4.41.0 and firecrawl-py 4.44.0. Other versions may send options we have not checked; anything we do not recognise is ignored and named in warning.

What runs where

Every /v2 request runs as one of our own operations. It uses the same API key, rate limit, credit balance and prices as the /v1 operation it maps to, and it is charged once.

/v2 routeCoverageRuns asNotes
POST /v2/scrapepartialPOST /v1/scrapeFormats markdown, rawHtml, html (the unprocessed page HTML), links, json (with a schema), summary, screenshot, branding. Actions: wait (milliseconds), click, write, press, scroll down, screenshot.
POST /v2/searchpartialPOST /v1/searchWeb results only. news and images come back in unsupported; no web results are substituted for them. scrapeOptions supports markdown only.
POST /v2/mappartialPOST /v1/mapurl, search, limit.
POST /v2/crawlpartialPOST /v1/crawllimit, includePaths, excludePaths, maxDiscoveryDepth, crawlEntireDomain, ignoreRobotsTxt, webhook (URL only). Pages come back as markdown.
GET /v2/crawl/:idsupportedGET /v1/crawl/:idAll stored pages in one response (next is always null). If a completed crawl's pages cannot be read, the answer is 502 results_unavailable, not an empty list.
DELETE /v2/crawl/:idsupportedDELETE /v1/crawl/:idCancels a queued or running crawl.
POST /v2/batch/scrapepartialPOST /v1/batch (async)Format markdown only. ignoreInvalidURLs, maxConcurrency, webhook (URL only).
GET /v2/batch/scrape/:idsupportedGET /v1/jobs/:idStatus and documents of an async batch.
POST /v2/parsepartialPOST /v1/parseMultipart file plus a JSON options field. Markdown output.

Not available on this door (each answers 404 with code: "operation_deferred"): async extract jobs (use POST /v1/extract, which is synchronous), batch cancel, crawl and batch error listings, the active-crawl listing, crawl planning from a prompt, team usage endpoints (use GET /v1/usage), agent jobs, browser sessions, interactive scrape sessions, monitors and feedback.

Options we refuse, and options we ignore

An option we cannot honour is either refused or named in warning.

  • Refused with 400: a format we do not produce (code: "unsupported_format"), an action we cannot run (unsupported_action, for example wait-for-selector or executeJavascript), redactPII, lockdown, profile, a crawl prompt, a crawl or batch format other than markdown, zeroDataRetention: true on crawl or batch, appendToId, and the x-idempotency-key header on batch. We do not deduplicate retries on that key, so we refuse it rather than risk charging a retry twice.
  • Ignored, and named in warning: options that only tune how a page is fetched, such as mobile, proxy, location, timeout, parsers and skipTlsVerification (TLS is always verified).
  • Cache: maxAge is honoured when you send it. When you do not, we fetch fresh.

Responses and errors

Successful responses use the { "success": true, ... } shape the clients expect. Every error, including authentication, rate limit and credit errors, uses:

{ "success": false, "error": "Credit balance exhausted", "code": "payment_required", "details": { "balance": 0, "required": 1 } }

401 means the key is missing, invalid or revoked (revocation applies from the next request). 402 means the monthly quota or the credit balance cannot cover the request; it is checked before any work runs. 429 carries Retry-After. The rate limit is shared with your /v1 traffic.

Moving to /v1

/v2 call/v1 equivalent
client.scrape(url, options)POST /v1/scrape
client.search(query, options)POST /v1/search
client.map(url, options)POST /v1/map
client.startCrawl(url), getCrawlStatus(id), cancelCrawl(id)POST /v1/crawl, GET /v1/crawl/:id plus GET /v1/crawl/:id/results, DELETE /v1/crawl/:id
client.startBatchScrape(urls), getBatchScrapeStatus(id)POST /v1/batch with async: true, then GET /v1/jobs/:id
client.parse(file)POST /v1/parse (multipart file)

The /v1 responses carry fields the migration door leaves out, such as the completeness score, the free JSON-LD listing and per-attempt fetch details.

What doesn't map 1:1

  • Completeness (_completeness) and provenance (_extraction_method, _provenance) fields exist on SuperScraper's /v1/scrape and /v1/extract responses and have no equivalent on the migration door. See Extract.
  • Only the Node and Python clients above have been tested against the door. Other clients may work if they send the same request shapes; call the REST API directly otherwise.

Trademark notice

Firecrawl is a trademark of its owner. SuperScraper is not affiliated with, sponsored by or endorsed by that owner. The name is used on this page only to identify the API and client libraries the /v2 door is compatible with.

CompletenessPricing