Rastrear

Firecrawl rastrea sitios web de forma eficiente para extraer datos completos mientras gestiona infraestructuras web complejas. El proceso:

Análisis de URL: Examina el sitemap y rastrea el sitio web para identificar enlaces
Recorrido: Sigue enlaces de manera recursiva para encontrar todas las subpáginas
Extracción (scraping): Extrae contenido de cada página, gestionando JS y límites de tasa
Salida: Convierte los datos a Markdown limpio o a un formato estructurado

Esto garantiza una recopilación exhaustiva de datos desde cualquier URL de partida.

Pruébalo en el Playground

Prueba el rastreo en el playground interactivo, sin escribir código.

Rastreo

punto de conexión /crawl

Se utiliza para rastrear una URL y todas las subpáginas accesibles. Esto envía un trabajo de rastreo y devuelve un ID de trabajo para verificar el estado del rastreo.

De forma predeterminada, el rastreador ignorará los enlaces de una página si no son descendientes directos de la URL que proporcionas. Así, website.com/other-parent/blog-1 no se devolvería si rastreas website.com/blogs/. Si quieres incluir website.com/other-parent/blog-1, usa el parámetro crawlEntireDomain. Para rastrear subdominios como blog.website.com al rastrear website.com, usa el parámetro allowSubdomains.

De forma predeterminada, el rastreador incluye el sitemap del sitio web para descubrir URLs (sitemap: "include"). Si configuras sitemap: "skip", el rastreador solo encontrará páginas accesibles a través de enlaces HTML que partan de la URL raíz. Recursos como PDFs o páginas muy anidadas que estén listadas en el sitemap pero no enlazadas directamente desde ninguna página HTML se omitirán. Para obtener la máxima cobertura, mantén la configuración predeterminada sitemap: "include".

Instalación

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-TU-API-KEY")

# npm install @mendable/firecrawl-js

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

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

# Instalar globalmente con npm
npm install -g firecrawl

# Autenticar (configuración de una sola vez)
firecrawl login

Uso

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-TU-API-KEY")

docs = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=10)
print(docs)

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

const firecrawl = new Firecrawl({ apiKey: "fc-TU-CLAVE-DE-API" });

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

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# Iniciar un trabajo de crawl (devuelve el ID del trabajo)
firecrawl crawl https://firecrawl.dev

# Wait for completion with progress
firecrawl crawl https://firecrawl.dev --wait --progress --limit 100

Cada página rastreada consume 1 crédito. El limit de rastreo predeterminado es de 10.000 páginas — establece un limit más bajo para controlar el consumo de créditos (por ejemplo, limit: 100). Se aplican créditos adicionales para ciertas opciones: el modo JSON cuesta 4 créditos adicionales por página, el proxy mejorado cuesta 4 créditos adicionales por página y el análisis de PDF cuesta 1 crédito por página de PDF.

Opciones de scraping en crawl

Todas las opciones del endpoint Scrape están disponibles en Crawl mediante scrapeOptions (JS) / scrape_options (Python). Se aplican a cada página que el crawler raspa: formatos, proxy, caché, acciones, ubicación, etiquetas, etc. Consulta la lista completa en la referencia de la API de Scrape.

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

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

// Crawl con opciones de scraping
const crawlResponse = await firecrawl.crawl('https://example.com', {
  limit: 100,
  scrapeOptions: {
    formats: [
      'markdown',
      {
        type: 'json',
        schema: { type: 'object', properties: { title: { type: 'string' } } },
      },
    ],
    proxy: 'auto',
    maxAge: 600000,
    onlyMainContent: true,
  },
});

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')

# Crawl con opciones de scraping
response = firecrawl.crawl('https://example.com',
    limit=100,
    scrape_options={
        'formats': [
            'markdown',
            { 'type': 'json', 'schema': { 'type': 'object', 'properties': { 'title': { 'type': 'string' } } } }
        ],
        'proxy': 'auto',
        'max_age': 600000,
        'only_main_content': True
    }
)

Respuesta de la API

Si usas cURL o el método starter, se devolverá un ID para verificar el estado del rastreo.

Si usas el SDK, consulta los métodos a continuación para conocer el comportamiento de waiter vs starter.

{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}

Consultar trabajo de rastreo

Se usa para verificar el estado de un trabajo de rastreo y obtener su resultado.

Los resultados de los trabajos están disponibles a través de la API durante 24 horas después de su finalización. Después de este periodo, aún puedes ver tu historial de rastreos y resultados en los activity logs.

Las páginas en el array data de los resultados del rastreo son páginas que Firecrawl extrajo correctamente, incluso si el sitio de destino devolvió un error HTTP como 404. El campo metadata.statusCode muestra el código de estado HTTP del sitio de destino. Para recuperar las páginas que Firecrawl no pudo extraer (por ejemplo, errores de red, tiempos de espera o bloqueos por robots.txt), usa el endpoint dedicado Get Crawl Errors (GET /crawl/{id}/errors).

estado = firecrawl.get_crawl_status("<crawl-id>")
print(estado)

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

# Después de iniciar un rastreo, consulta el estado por jobId
curl -s -X GET "https://api.firecrawl.dev/v2/crawl/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# Verificar estado del crawl usando el ID del trabajo
firecrawl crawl <job-id>

Manejo de respuestas

La respuesta varía según el estado del rastreo. Para respuestas incompletas o de gran tamaño que superen los 10 MB, se proporciona un parámetro de URL next. Debes solicitar esta URL para obtener los siguientes 10 MB de datos. Si el parámetro next no está presente, indica el final de los datos del rastreo. El parámetro skip define el número máximo de resultados incluidos en cada bloque de resultados devueltos.

Los parámetros skip y next solo son relevantes cuando se consume la API directamente. Si usas el SDK, nos encargamos de esto por ti y devolveremos todos los resultados de una vez.

{
  "status": "en proceso de scraping",
  "total": 36,
  "completed": 10,
  "creditsUsed": 10,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=10",
  "data": [
    {
      "markdown": "[Página principal de la documentación de Firecrawl![logo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
      "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
      "metadata": {
        "title": "Crea un 'chat con el sitio web' usando Groq Llama 3 | Firecrawl",
        "language": "en",
        "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
        "description": "Aprende a usar Firecrawl, Groq Llama 3 y LangChain para crear un bot de 'chat con tu sitio web'."
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

{
  "status": "completado",
  "total": 36,
  "completed": 36,
  "creditsUsed": 36,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=26",
  "data": [
    {
      "markdown": "[Página principal de la documentación de Firecrawl![logotipo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
      "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
      "metadata": {
        "title": "Crea un ‘chat con el sitio web’ usando Groq Llama 3 | Firecrawl",
        "language": "en",
        "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
        "description": "Aprende a usar Firecrawl, Groq Llama 3 y LangChain para crear un bot de ‘chat con tu sitio web’."
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

Métodos del SDK

Hay dos maneras de usar el SDK:

Rastrear y esperar (crawl):
- Espera a que el rastreo termine y devuelve la respuesta completa
- Gestiona la paginación automáticamente
- Recomendado para la mayoría de los casos de uso

from firecrawl import Firecrawl
from firecrawl.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# Rastrear un sitio web:
crawl_status = firecrawl.crawl(
  'https://firecrawl.dev', 
  limit=100, 
  scrape_options=ScrapeOptions(formats=['markdown', 'html']),
  poll_interval=30
)
print(crawl_status)

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

const firecrawl = new Firecrawl({ apiKey: "fc-TU_API_KEY" });

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

console.log(crawlResponse)

La respuesta incluye el estado del rastreo y todos los datos extraídos:

success=True
status='completed'
completed=100
total=100
creditsUsed=100
expiresAt=datetime.datetime(2025, 4, 23, 19, 21, 17, tzinfo=TzInfo(UTC))
next=None
data=[
  Document(
    markdown='[Día 7 - Semana de lanzamiento III. Día de integraciones (del 14 al 20 de abril)](...',
    metadata={
      'title': '15 proyectos de web scraping con Python: de principiante a avanzado',
      ...
      'scrapeId': '97dcf796-c09b-43c9-b4f7-868a7a5af722',
      'sourceURL': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'url': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'statusCode': 200
    }
  ),
  ...
]

{
  success: true,
  status: "finalizado",
  completed: 100,
  total: 100,
  creditsUsed: 100,
  expiresAt: "2025-04-23T19:28:45.000Z",
  data: [
    {
      markdown: "[Día 7 - Semana de lanzamiento III. Día de integraciones Abril ...",
      html: `<!DOCTYPE html><html lang="en" class="light" style="color...`,
      metadata: [Object],
    },
    ...
  ]
}

Iniciar y luego verificar el estado (startCrawl/start_crawl):
- Devuelve de inmediato un ID de rastreo
- Permite verificar el estado manualmente
- Útil para rastreos de larga duración o lógica de sondeo personalizada

from firecrawl import Firecrawl

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

job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
print(job)

# Comprueba el estado del rastreo
status = firecrawl.get_crawl_status(job.id)
print(status)

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

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

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

// Comprueba el estado del rastreo
const status = await firecrawl.getCrawlStatus(id);
console.log(status);

curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "limit": 10
  }'

# Iniciar rastreo (asíncrono, devuelve ID de trabajo inmediatamente)
firecrawl crawl https://firecrawl.dev --limit 100

# Then check status later
firecrawl crawl <job-id>

WebSocket de rastreo

El método de Firecrawl basado en WebSocket, Crawl URL and Watch, permite la extracción y el monitoreo de datos en tiempo real. Inicia un rastreo con una URL y personalízalo con opciones como límites de páginas, dominios permitidos y formatos de salida; ideal para necesidades de procesamiento de datos inmediatas.

import asyncio
from firecrawl import AsyncFirecrawl

async def main():
    firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

    # Iniciar un rastreo primero
    started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)

    # Monitorear actualizaciones (snapshots) hasta estado terminal
    async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
        if snapshot.status == "completed":
            print("COMPLETADO", snapshot.status)
            for doc in snapshot.data:
                print("DOC", doc.metadata.source_url if doc.metadata else None)
        elif snapshot.status == "failed":
            print("ERROR", snapshot.status)
        else:
            print("ESTADO", snapshot.status, snapshot.completed, "/", snapshot.total)

asyncio.run(main())

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

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

// Inicia un rastreo y luego míralo
const { 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();

Webhook de rastreo

Puedes configurar webhooks para recibir notificaciones en tiempo real a medida que avanza el rastreo. Esto te permite procesar las páginas conforme se van extrayendo, en lugar de esperar a que finalice todo el rastreo.

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://tu-dominio.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

Referencia rápida

Tipos de eventos:

crawl.started - Cuando se inicia el rastreo
crawl.page - Por cada página extraída correctamente
crawl.completed - Cuando finaliza el rastreo
crawl.failed - Si ocurre un error durante el rastreo

Carga útil básica:

{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Datos de página para eventos 'page'
  "metadata": {}, // Your custom metadata
  "error": null
}

Seguridad: Verificación de firmas de webhooks

Cada solicitud de webhook de Firecrawl incluye un encabezado X-Firecrawl-Signature que contiene una firma HMAC-SHA256. Verifica siempre esta firma para asegurarte de que el webhook sea auténtico y no haya sido manipulado. Cómo funciona:

Obtén tu secreto de webhook en la pestaña Advanced de la configuración de tu cuenta
Extrae la firma del encabezado X-Firecrawl-Signature
Calcula el HMAC-SHA256 del cuerpo sin procesar (raw) de la solicitud usando tu secreto
Compárala con el encabezado de la firma usando una función segura frente a ataques de temporización

Nunca proceses un webhook sin verificar primero su firma. El encabezado X-Firecrawl-Signature contiene la firma en el formato: sha256=abc123def456...

Para ver ejemplos completos de implementación en JavaScript y Python, consulta la documentación de seguridad de webhooks.

Documentación completa

Para una documentación completa sobre webhooks, incluidos payloads de eventos detallados, la estructura del payload, configuración avanzada y resolución de problemas, consulta la documentación de webhooks.

Primeros pasos

Novedades

Funciones principales

Guías para desarrolladores

Webhooks

Casos de uso

Contribuir

Pruébalo en el Playground

Rastreo

punto de conexión /crawl

Instalación

Uso

Opciones de scraping en crawl

Respuesta de la API

Consultar trabajo de rastreo

Manejo de respuestas

Métodos del SDK

WebSocket de rastreo

Webhook de rastreo

Referencia rápida

Seguridad: Verificación de firmas de webhooks

Documentación completa

Pruébalo en el Playground

​Rastreo

​punto de conexión /crawl

​Instalación

​Uso

​Opciones de scraping en crawl

​Respuesta de la API

​Consultar trabajo de rastreo

​Manejo de respuestas

​Métodos del SDK

​WebSocket de rastreo

​Webhook de rastreo

​Referencia rápida

​Seguridad: Verificación de firmas de webhooks

​Documentación completa

Rastreo

punto de conexión /crawl

Instalación

Uso

Opciones de scraping en crawl

Respuesta de la API

Consultar trabajo de rastreo

Manejo de respuestas

Métodos del SDK

WebSocket de rastreo

Webhook de rastreo

Referencia rápida

Seguridad: Verificación de firmas de webhooks

Documentación completa