Node - Firecrawl Docs

Scrapez des pages individuelles, lancez un crawl sur des sites entiers et cartographiez les URL depuis votre application Node.js. Le SDK gère la pagination, les nouvelles tentatives et l’interrogation asynchrone des tâches pour que vous puissiez vous concentrer sur l’exploitation des données retournées.

Installation#

Installez le SDK avec npm :

Node

// npm install firecrawlimport { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :  // apiKey: "fc-YOUR-API-KEY",});

Utilisation#

Récupérez une clé d’API sur firecrawl.dev
Définissez la clé d’API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou transmettez-la en paramètre à la classe Firecrawl.

Note

Pas de clé d’API ? Vous pouvez instancier Firecrawl sans clé et utiliser scrape, search et interact sur l’offre Free sans clé (avec une limite de débit par IP — voir Limites de débit). Toutes les autres méthodes nécessitent une clé.

Voici un exemple d’utilisation du SDK avec gestion des erreurs :

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});// Récupérer le contenu d'un site webconst scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {  formats: ['markdown', 'html'],});console.log(scrapeResponse)// Explorer un site webconst crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {  limit: 100,  scrapeOptions: {    formats: ['markdown', 'html'],  }});console.log(crawlResponse)

Scraper une URL#

Récupérez les données structurées d’une page à partir d’une URL avec la méthode scrape.

Node.js

// Extraire le contenu d’un site :const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });console.log(scrapeResult)

Analyse des fichiers importés#

Utilisez parse lorsque vous souhaitez importer un fichier local (html, pdf, docx, xlsx, etc.) au lieu d’effectuer du scraping à partir d’une URL. parse ne prend pas en charge changeTracking ni les options propres au navigateur comme screenshot, branding, actions, waitFor, location et mobile.

Node

const parsed = await firecrawl.parse(  {    data: "<html><body><h1>Node Parse</h1></body></html>",    filename: "upload.html",    contentType: "text/html",  },  {    formats: ["markdown"],  },);console.log(parsed.markdown);

Crawl d’un site web#

Crawlez l’ensemble d’un site web à partir d’une seule URL avec la méthode crawl. Vous pouvez définir une limite de pages, restreindre le crawl à des domaines spécifiques et choisir les formats de sortie. Consultez Pagination pour la pagination automatique et manuelle.

Node.js

const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });console.log(job.status);

Crawl uniquement via le sitemap#

Utilisez sitemap: "only" pour explorer uniquement les URL du sitemap (l’URL de départ est toujours incluse et la découverte de liens HTML est désactivée).

Node

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

Démarrer un crawl#

Lancez un crawl sans attendre qu’il se termine avec startCrawl. La méthode renvoie un ID de tâche que vous pourrez interroger plus tard. Utilisez plutôt crawl lorsque vous voulez bloquer jusqu’à la fin. Voir Pagination pour le comportement de pagination et les limites.

Node

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

Vérifier l’état du crawl#

Vérifiez si un crawl est toujours en cours, terminé ou a échoué avec la méthode checkCrawlStatus. Passez l’ID de tâche renvoyé par startCrawl.

Node

const status = await firecrawl.getCrawlStatus("<crawl-id>");console.log(status);

Annuler un crawl#

Annulez un crawl en cours avec la méthode cancelCrawl. Passez l’ID de tâche renvoyé par startCrawl.

Node

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

Cartographier un site web#

Découvrez toutes les URL d’un site web avec la méthode map. Fournissez une URL de départ et obtenez en retour la liste des pages découvertes.

Node.js

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

Exécuter un agent#

Confiez une tâche de recherche ou d’extraction à un agent à l’aide de la méthode agent. Fournissez un prompt, un schema facultatif pour structurer la sortie et maxCredits pour plafonner les crédits que l’exécution peut consommer.

Node

import { Firecrawl } from 'firecrawl';import { z } from 'zod';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });const result = await firecrawl.agent({  prompt: "Find the founders of Firecrawl",  schema: z.object({    founders: z.array(z.object({      name: z.string().describe("Full name of the founder"),      role: z.string().describe("Role or position").optional(),      background: z.string().describe("Professional background").optional()    })).describe("List of founders")  }),  model: "spark-2",  maxCredits: 100});console.log(result.data);

Les exécutions d’agent sont asynchrones. Utilisez startAgent pour obtenir immédiatement un ID de tâche, puis interrogez son état avec getAgentStatus.

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });// Lancer une tâche d'agentconst started = await firecrawl.startAgent({  prompt: "Find the founders of Firecrawl"});// Vérifier le statutif (started.id) {  const status = await firecrawl.getAgentStatus(started.id);  console.log(status.status, status.data);}

Chaque exécution enregistre également une trace d’exécution et des instantanés de sortie, que vous pouvez consulter avec getAgentTrace et getAgentSnapshot. Consultez Agent pour le schéma des événements et la liste complète des paramètres.

Crawler un site web avec WebSockets#

Recevez les résultats du crawl en temps réel avec watcher(jobId, options). Vous recevez chaque page dès qu’elle est explorée, au lieu d’attendre la fin de la tâche complète.

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });// Lancer un crawl puis le suivreconst { 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);});watcher.on('error', (err) => {  console.error('ERR', err?.error || err);});watcher.on('done', (state) => {  console.log('DONE', state.status);});// Démarrer l'observation (WS avec solution de repli HTTP)await watcher.start();

Pagination#

Les points de terminaison Firecrawl pour crawl et batch renvoient une URL next lorsqu’il reste des données. Le SDK Node effectue, par défaut, une pagination automatique et agrège tous les documents ; dans ce cas, next vaut null. Vous pouvez désactiver la pagination automatique ou définir des limites.

Crawl#

Utilisez la méthode d’attente crawl pour la solution la plus simple, ou démarrez un job et paginez manuellement.

Exploration simple (pagination automatique, par défaut)

Voir le flux par défaut dans Exploration d’un site web.

Crawl manuel avec contrôle de la pagination (page unique)

Lancez un job, puis récupérez les pages une par une avec autoPaginate: false.

Node

const crawlStart = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 5 });const crawlJobId = crawlStart.id;const crawlSingle = await firecrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });console.log('exploration d’une seule page :', crawlSingle.status, 'docs :', crawlSingle.data.length, 'suivant :', crawlSingle.next);

Exploration manuelle avec limites (pagination automatique + arrêt anticipé)

Conservez la pagination automatique activée, mais arrêtez plus tôt avec maxPages, maxResults ou maxWaitTime.

Node

const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {  autoPaginate: true,  maxPages: 2,  maxResults: 50,  maxWaitTime: 15,});console.log('exploration limitée :', crawlLimited.status, 'docs :', crawlLimited.data.length, 'suivant :', crawlLimited.next);

Scrape par lots#

Utilisez la méthode du waiter batchScrape, ou lancez un job et paginez manuellement.

Collecte par lots simple (pagination automatique, par défaut)

Voir le flux par défaut dans Batch Scrape.

Scraping par lots manuel avec contrôle de la pagination (page unique)

Lancez un job, puis récupérez les pages une par une avec autoPaginate: false.

Node

const batchStart = await firecrawl.startBatchScrape([  'https://docs.firecrawl.dev',  'https://firecrawl.dev',], { options: { formats: ['markdown'] } });const batchJobId = batchStart.id;const batchSingle = await firecrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });console.log('lot page unique :', batchSingle.status, 'docs :', batchSingle.data.length, 'suivant :', batchSingle.next);

Scrape manuel par lots avec limites (pagination automatique + arrêt anticipé)

Laissez la pagination automatique activée, mais arrêtez plus tôt avec maxPages, maxResults ou maxWaitTime.

Node

const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {  autoPaginate: true,  maxPages: 2,  maxResults: 100,  maxWaitTime: 20,});console.log('lot limité :', batchLimited.status, 'docs :', batchLimited.data.length, 'suivant :', batchLimited.next);

Navigateur#

Démarrez des sessions de navigateur dans le cloud et exécutez du code à distance.

Créer une session#

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });const session = await firecrawl.browser({ ttl: 600 });console.log(session.id);          // ID de sessionconsole.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

Exécuter du code#

Node

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

Exécutez JavaScript plutôt que Python :

Node

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

Exécutez Bash avec agent-browser :

Node

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

Profils#

Enregistrez et réutilisez l’état du navigateur (cookies, localStorage, etc.) d’une session à l’autre :

Node

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

Connexion via le CDP#

Pour bénéficier d’un contrôle complet via Playwright, connectez-vous directement à l’aide de l’URL CDP :

Node

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

Lister & fermer les sessions#

Node

// Lister les sessions activesconst { sessions } = await firecrawl.listBrowsers({ status: "active" });for (const s of sessions) {  console.log(s.id, s.status, s.createdAt);}// Fermer une sessionawait firecrawl.deleteBrowser(session.id);

Session interactive liée au scraping#

Utilisez l’ID d’une tâche de scraping pour continuer à interagir avec le contexte de page rejoué de ce scraping :

interact(jobId, {...}) exécute du code dans la session de navigateur liée au scraping.
Le premier appel à interact initialise automatiquement la session à partir du contexte de scraping.
Les appels suivants à interact avec le même ID de tâche réutilisent cet état actif du navigateur.
stopInteraction(jobId) arrête la session interactive une fois que vous avez terminé.

Node

const doc = await firecrawl.scrape("https://example.com", {  actions: [{ type: "click", selector: "a[href='/pricing']" }],});const scrapeJobId = doc.metadata?.scrapeId;if (!scrapeJobId) throw new Error("Missing scrape job id");const run = await firecrawl.interact(scrapeJobId, {  code: "console.log(await page.url())",  language: "node",  timeout: 60,});console.log(run.stdout);await firecrawl.stopInteraction(scrapeJobId);

Gestion des erreurs#

Le SDK lève des exceptions explicites pour toute erreur renvoyée par l’API Firecrawl. Encadrez les appels dans des blocs try/catch, comme dans les exemples ci-dessus.

Êtes-vous un agent IA qui a besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir des instructions d’onboarding automatisé.