Saltar al contenido principal
Rastrear envía una URL a Firecrawl y descubre y extrae de forma recursiva todas las subpáginas accesibles. Gestiona automáticamente sitemaps, renderizado de JavaScript y límites de tasa, y devuelve Markdown limpio o datos estructurados para cada página.
  • Descubre páginas mediante sitemap y recorrido recursivo de enlaces
  • Admite filtrado por ruta, límites de profundidad y control de subdominios/enlaces externos
  • Devuelve resultados mediante polling, WebSocket o webhook

Pruébalo en el Playground

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

​
Instalación

# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
Uso básico

Envía un trabajo de rastreo llamando a POST /v2/crawl con una URL inicial. El endpoint devuelve un ID de trabajo que usas para consultar los resultados. 
from firecrawl import Firecrawl

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

docs = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=10)
print(docs)
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

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, incluidos formatos, proxy, caché, acciones, ubicación y etiquetas. 
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
    }
)

​
Verificar el estado del rastreo

Usa el ID del trabajo para consultar el estado del rastreo y recuperar los resultados. 
estado = firecrawl.get_crawl_status("<crawl-id>")
print(estado)
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).

​
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.
Los parámetros skip y next solo son relevantes cuando se consume la API directamente. Si usas el SDK, la paginación se gestiona automáticamente y todos los resultados se devuelven 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
      }
    },
    ...
  ]
}

​
Métodos del SDK

Hay dos maneras de usar crawl con el SDK.

​
Rastrear y esperar

El método crawl espera a que el rastreo termine y devuelve la respuesta completa. Gestiona la paginación automáticamente. Esto se recomienda 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)
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
    }
  ),
  ...
]

​
Iniciar y luego verificar el estado

El método startCrawl / start_crawl devuelve de inmediato un ID de rastreo. Luego puedes verificar el estado manualmente. Esto es ú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)
La respuesta inicial devuelve el ID del trabajo: 
{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}

​
Resultados en tiempo real con WebSocket

El método watcher proporciona actualizaciones en tiempo real a medida que se rastrean las páginas. Inicia un rastreo y luego suscríbete a los eventos para procesar los datos de inmediato. 
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())

​
Webhooks

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"]
      }
    }'

​
Tipos de eventos

EventoDescripción
crawl.startedSe emite cuando comienza el rastreo
crawl.pageSe emite por cada página extraída correctamente
crawl.completedSe emite cuando finaliza el rastreo
crawl.failedSe emite si el rastreo encuentra un error

​
Carga útil

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

​
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.
  1. Obtén tu secreto de webhook en la pestaña Advanced de la configuración de tu cuenta
  2. Extrae la firma del encabezado X-Firecrawl-Signature
  3. Calcula el HMAC-SHA256 del cuerpo sin procesar (raw) de la solicitud usando tu secreto
  4. 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. Para consultar la documentación completa sobre webhooks, incluidos payloads de eventos detallados, estructura de payloads, configuración avanzada y solución de problemas, consulta la documentación de webhooks.

​
Referencia de configuración

El conjunto completo de parámetros disponibles al enviar una tarea de rastreo:
ParámetroTipoPredeterminadoDescripción
urlstring(obligatorio)La URL inicial desde la que se realizará el rastreo
limitinteger10000Número máximo de páginas que se rastrearán
maxDiscoveryDepthinteger(ninguno)Profundidad máxima desde la URL raíz según el orden de descubrimiento. El sitio raíz y las páginas del sitemap tienen una profundidad de descubrimiento de 0.
includePathsstring[](ninguno)Patrones regex de rutas de URL que se incluirán. Solo se rastrean las rutas que coinciden.
excludePathsstring[](ninguno)Patrones regex de rutas de URL que se excluirán del rastreo
regexOnFullURLbooleanfalseHace coincidir includePaths/excludePaths con la URL completa (incluidos los parámetros de consulta) en lugar de solo con la ruta
crawlEntireDomainbooleanfalseSigue enlaces internos a URL del mismo nivel o superiores, no solo a rutas hijas
allowSubdomainsbooleanfalseSigue enlaces a subdominios del dominio principal
allowExternalLinksbooleanfalseSigue enlaces a sitios web externos
sitemapstring"include"Gestión del sitemap: "include" (predeterminado), "skip" o "only"
ignoreQueryParametersbooleanfalseEvita volver a extraer la misma ruta con distintos parámetros de consulta
delaynumber(ninguno)Retraso en segundos entre extracciones para respetar los límites de tasa
maxConcurrencyinteger(ninguno)Número máximo de extracciones concurrentes. De forma predeterminada, usa el límite de concurrencia de tu equipo.
scrapeOptionsobject(ninguno)Opciones aplicadas a cada página extraída (formatos, proxy, caché, acciones, etc.)
webhookobject(ninguno)Configuración del webhook para notificaciones en tiempo real
promptstring(ninguno)Prompt en lenguaje natural para generar opciones de rastreo. Los parámetros establecidos explícitamente anulan los equivalentes generados.

​
Detalles importantes

De forma predeterminada, crawl ignora los subenlaces que no son descendientes de la URL que proporcionas. Por ejemplo, website.com/other-parent/blog-1 no se devolvería si hicieras crawl de website.com/blogs/. Usa el parámetro crawlEntireDomain para incluir rutas hermanas y superiores. Para hacer crawl de subdominios como blog.website.com al hacer crawl de website.com, usa el parámetro allowSubdomains.
  • Descubrimiento del sitemap: De forma predeterminada, el crawler incluye el sitemap del sitio web para descubrir URL (sitemap: "include"). Si estableces sitemap: "skip", solo se encontrarán las páginas accesibles mediante enlaces HTML desde la URL raíz. Recursos como PDF o páginas muy anidadas incluidas en el sitemap, pero no enlazadas directamente desde el HTML, no se encontrarán. Para obtener la máxima cobertura, mantén la configuración predeterminada.
  • Uso de créditos: Cada página rastreada cuesta 1 crédito. El modo JSON añade 4 créditos por página, el proxy mejorado añade 4 créditos por página y el análisis de PDF cuesta 1 crédito por cada página del PDF.
  • Expiración de resultados: Los resultados del trabajo están disponibles a través de la API durante 24 horas después de completarse. Después de ese plazo, consulta los resultados en los registros de actividad.
  • Errores de crawl: El array data contiene las páginas que Firecrawl extrajo correctamente. Usa el endpoint Get Crawl Errors para recuperar las páginas que fallaron debido a errores de red, tiempos de espera o bloqueos de robots.txt.