Rastrear

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

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.

Todas las opciones del endpoint Scrape están disponibles en rastreo 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 Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')# Crawl con opciones de scrapingresponse = 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    })

Usa el ID del trabajo para consultar el estado del rastreo y recuperar los resultados.

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.

Hay dos maneras de usar crawl con el SDK.

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.

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

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.

La respuesta inicial devuelve el ID del trabajo:

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

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.

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

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

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

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.

El conjunto completo de parámetros disponibles al enviar un trabajo de rastreo:

• 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 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 activity logs.
• Errores de rastreo: 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.
• Enlaces externos: Con allowExternalLinks: true, el crawler sigue los enlaces que apuntan fuera de tu dominio y scrapea cada página enlazada una vez; después no rastrea los enlaces encontrados en esas páginas externas. Los enlaces a la página de inicio de un sitio externo (una URL raíz sin ruta, por ejemplo, https://example.com/) se omiten intencionadamente para evitar incluir un sitio no relacionado completo; estos aparecen en Get Crawl Errors con el código EXTERNAL_LINK. Se siguen las redirecciones hasta su destino, incluido un enlace que se resuelve en su URL canónica (por ejemplo, http → https o la variante www), por lo que solo se omiten las redirecciones que llegan a una página de inicio externa.
• Resultados no deterministas: Los resultados del rastreo pueden variar entre ejecuciones con la misma configuración. Las páginas se extraen de forma concurrente, por lo que el orden en que se descubren los enlaces depende de la latencia de la red y de qué páginas terminan de cargarse primero. Esto significa que diferentes ramas de un sitio pueden explorarse en distinta medida cerca del límite de profundidad, especialmente con valores altos de maxDiscoveryDepth. Para obtener resultados más deterministas, establece maxConcurrency en 1 o usa sitemap: "only" si el sitio tiene un sitemap completo.

¿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.