Node - Firecrawl Docs

Haz scraping de páginas individuales, rastrea sitios completos y mapea URL desde tu aplicación Node.js. El SDK gestiona la paginación, los reintentos y la consulta asíncrona del estado de los trabajos para que puedas centrarte en trabajar con los datos devueltos.

Instalación#

Instala el SDK con npm:

Node

// npm install firecrawlimport { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({  // No se necesita API key para comenzar — agrega una para obtener límites de tasa más altos:  // apiKey: "fc-YOUR-API-KEY",});

Uso#

Obtén una clave de API en firecrawl.dev
Define la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala como parámetro a la clase Firecrawl.

Note

¿No tienes una clave de API? Puedes crear Firecrawl sin una clave y usar scrape, search e interact en el plan Free sin clave (limitado por IP; consulta Rate Limits). Todos los demás métodos requieren una clave.

Aquí tienes un ejemplo de cómo usar el SDK con manejo de errores:

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});// Extraer datos de un sitio webconst scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {  formats: ['markdown', 'html'],});console.log(scrapeResponse)// Rastrear un sitio webconst crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {  limit: 100,  scrapeOptions: {    formats: ['markdown', 'html'],  }});console.log(crawlResponse)

Extracción de una URL#

Extrae una sola URL y obtén datos estructurados de la página con el método scrape.

Node.js

// Extraer un sitio web:const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });console.log(scrapeResult)

Análisis de archivos subidos#

Usa parse cuando quieras subir un archivo local (html, pdf, docx, xlsx, etc.) en lugar de hacer scraping mediante una URL. parse no admite changeTracking ni opciones exclusivas del navegador, como screenshot, branding, actions, waitFor, location y 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);

Rastreo de un sitio web#

Rastrea un sitio web completo a partir de una sola URL con el método crawl. Puedes establecer un límite de páginas, restringir el rastreo a dominios específicos y seleccionar formatos de salida. Consulta Pagination para la paginación automática y manual.

Node

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

Rastreo solo del sitemap#

Usa sitemap: "only" para rastrear únicamente las URL del sitemap (la URL inicial siempre se incluye y se omite la detección de enlaces HTML).

Node

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

Iniciar un rastreo#

Inicia un rastreo sin esperar a que termine usando startCrawl. El método devuelve un ID de trabajo que puedes consultar más tarde. Usa crawl en su lugar cuando quieras bloquear hasta que finalice. Consulta Paginación para el comportamiento y los límites de paginación.

Node

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

Consultar el estado del rastreo#

Verifica si un rastreo sigue en ejecución, se ha completado o ha fallado con el método checkCrawlStatus. Proporciona el ID de trabajo devuelto por startCrawl.

Node.js

const estado = await firecrawl.getCrawlStatus("<id-de-rastreo>");console.log(estado);

Cancelar un rastreo#

Cancela un rastreo en curso con el método cancelCrawl. Pasa el ID de trabajo que devuelve startCrawl.

Node

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

Mapear un sitio web#

Descubre todas las URL de un sitio web con el método map. Pasa una URL inicial y obtén una lista de las páginas detectadas.

Node

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

Ejecutar un agente#

Asigna una tarea de investigación o extracción a un agente mediante el método agent. Proporciona un prompt, un schema opcional para definir la salida y maxCredits para limitar el gasto de la ejecución.

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

Las ejecuciones de agentes son asíncronas. Usa startAgent para obtener un ID de trabajo de inmediato y luego consulta su estado con getAgentStatus.

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });// Inicia una tarea de agenteconst started = await firecrawl.startAgent({  prompt: "Find the founders of Firecrawl"});// Verifica el estadoif (started.id) {  const status = await firecrawl.getAgentStatus(started.id);  console.log(status.status, status.data);}

Cada ejecución también registra una traza de ejecución e instantáneas de salida, que puedes consultar con getAgentTrace y getAgentSnapshot. Consulta Agent para ver el esquema de eventos y la lista completa de parámetros.

Rastreo de un sitio web con WebSockets#

Obtén los resultados del rastreo en tiempo real con watcher(jobId, options). Recibirás cada página a medida que se rastrea, en lugar de esperar a que termine todo el trabajo.

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });// Inicia un rastreo y luego míraloconst { 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);});// Comienza a mirar (WS con alternativa HTTP)await watcher.start();

Paginación#

Los puntos de conexión de Firecrawl para crawl y batch devuelven una URL next cuando hay más datos disponibles. El SDK de Node realiza la paginación automáticamente por defecto y agrega todos los documentos; en ese caso, next será null. Puedes desactivar la paginación automática o establecer límites.

Rastreo#

Usa el método auxiliar crawl para la forma más sencilla, o inicia un job y pagina manualmente.

Rastreo simple (paginación automática, por defecto)

Consulta el flujo por defecto en Rastrear un sitio web.

Rastreo manual con control de paginación (una sola página)

Inicia un trabajo y luego recupera una página a la vez con autoPaginate: false.

Nodo

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('rastreo de una sola página:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'siguiente:', crawlSingle.next);

Rastreo manual con límites (paginación automática + parada anticipada)

Mantén la paginación automática activada, pero deténla antes con maxPages, maxResults o maxWaitTime.

Node

const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {  autoPaginate: true,  maxPages: 2,  maxResults: 50,  maxWaitTime: 15,});console.log('rastreo limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'siguiente:', crawlLimited.next);

Scrape por lotes#

Usa el método waiter batchScrape, o inicia un job y pagina manualmente.

Raspado por lotes simple (paginación automática, predeterminado)

Consulta el flujo predeterminado en Raspado por lotes.

Raspado manual por lotes con control de paginación (una sola página)

Inicia un job y luego recupera una página a la vez con 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('lote, una sola página:', batchSingle.status, 'docs:', batchSingle.data.length, 'siguiente:', batchSingle.next);

Extracción manual por lotes con límites (paginación automática + detención anticipada)

Mantén la paginación automática activada, pero deténla antes con maxPages, maxResults o maxWaitTime.

Node

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

Browser#

Inicia sesiones de navegador en la nube y ejecuta código de forma remota.

Crear una sesión#

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 sesiónconsole.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

Ejecutar código#

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"

Ejecuta JavaScript en lugar de 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",});

Ejecuta Bash con agent-browser:

Node

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

Perfiles#

Guarda y reutiliza el estado del navegador (cookies, localStorage, etc.) entre distintas sesiones:

Node

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

Conectar mediante CDP#

Para obtener control completo de Playwright, conecta directamente usando la URL de 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();

Listar & cerrar sesiones#

Node

// Listar sesiones activasconst { sessions } = await firecrawl.listBrowsers({ status: "active" });for (const s of sessions) {  console.log(s.id, s.status, s.createdAt);}// Cerrar una sesiónawait firecrawl.deleteBrowser(session.id);

Sesión interactiva vinculada al scraping#

Usa un ID de trabajo de scraping para seguir interactuando con el contexto reproducido de la página de ese scraping:

interact(jobId, {...}) ejecuta código en la sesión del navegador vinculada al scraping.
La primera llamada a interact inicializa automáticamente la sesión a partir del contexto del scraping.
Las llamadas adicionales a interact con el mismo ID de trabajo reutilizan ese estado activo del navegador.
stopInteraction(jobId) detiene la sesión interactiva cuando termines.

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

Manejo de errores#

El SDK arroja excepciones descriptivas para cualquier error devuelto por la API de Firecrawl. Envuelve las llamadas en bloques try/catch, como se muestra en los ejemplos anteriores.

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para obtener instrucciones de incorporación automatizada.