crawl_deep
Recorra un sitio hacia fuera desde una URL inicial, en anchura, siguiendo enlaces hasta alcanzar su límite de páginas o de profundidad. Devuelve cada página alcanzada con su título, su profundidad desde el inicio y cuántos enlaces encontró allí.
Casos de uso
Mapear un sitio de documentación
Empiece en la raíz de la documentación y descubra todas las páginas alcanzables, con la profundidad mostrando cómo se anida la información.
Construir una lista de URL antes de un scraping por lotes
Rastree para descubrir URL y luego páselas a batch_scrape para extraer contenido: más económico que rastrear con extracción completa.
Auditar el enlazado interno
El número de enlaces por página y la distribución de profundidad muestran qué secciones están bien enlazadas y cuáles quedan casi huérfanas.
Comprobar a qué profundidad está realmente su contenido
pages_per_depth revela si las páginas importantes están a tres o cuatro clics del punto de entrada.
Endpoint
/api/v1/tools/crawl_deepParameters
start_url, no url. Todos los parámetros usan snake_case: las claves desconocidas se descartan en silencio en lugar de rechazarse, así que una clave en camelCase como maxDepth se ignora y se usa el valor predeterminado.| Name | Type | Required | Default | Description |
|---|---|---|---|---|
start_url | string | Required | - | La URL desde la que comienza el rastreo. Obligatorio. Example: https://example.com/docs |
max_pages | number | Optional | 10 | Número máximo de páginas a visitar, 1-100. El rastreo se detiene en cuanto se han visitado esas páginas, por lo que también limita el costo y la duración. Example: 25 |
max_depth | number | Optional | 3 | Profundidad máxima de enlaces desde `start_url`, 1-5. La página inicial es la profundidad 0. Example: 2 |
same_domain_only | boolean | Optional | true | Cuando es true, solo se siguen los enlaces cuyo host coincide con el de `start_url`. Los enlaces externos siguen contando en los totales de enlaces, pero nunca se visitan. Example: true |
respect_robots_txt | boolean | Optional | true | Cuando es true, el robots.txt de cada origen se descarga una vez por rastreo y se omite toda URL que no permita a `CrawlForge`. Un robots.txt ausente o inaccesible se trata como ausencia de restricciones. Alias antiguo de `respect_robots`; ambos nombres configuran lo mismo. Example: true |
respect_robots | boolean | Optional | true | Respeta el robots.txt de cada origen. Este es el nombre canónico, compartido con el servidor MCP de CrawlForge; `respect_robots_txt` es el alias antiguo y sigue funcionando: puede usar cualquiera de los dos. Con el valor `true`, un `start_url` no permitido se rechaza con un 403 antes de descargar nada y las páginas no permitidas se omiten durante el rastreo. Póngalo en `false` solo para sitios con los que tenga su propio acuerdo: la respuesta incluye entonces una entrada `warnings` y la anulación queda registrada en su API key. Example: true |
crawl_delay | number | Optional | 1000 | Milisegundos de espera entre solicitudes de páginas, 0-5000. Se aplica a partir de la segunda página. Auméntelo para sitios pequeños o con límites de tasa. Example: 1000 |
timeout | number | Optional | 30000 | Presupuesto total del rastreo en milisegundos, 1000-60000, dividido en partes iguales entre `max_pages` para dar a cada solicitud su propio tiempo límite. Por tanto, aumentar `max_pages` reduce el tiempo permitido a cada página. Example: 30000 |
CrawlForge, y robots.txt se respeta de forma predeterminada. Las reglas de cada origen se descargan una vez por rastreo y se almacenan en caché. Las URL no permitidas se omiten sin consumir su presupuesto de max_pages, y una start_url no permitida devuelve 403 antes de descargar nada, así que un rastreo bloqueado no cuesta credits.Cómo se comporta el rastreo
Conviene saberlo antes de leer las cifras que devuelve.
max_pages bajo obtiene un mapa amplio y superficial en lugar de una sola rama profunda.pages y el rastreo continúa. pages_crawled puede ser menor que max_pages sin indicación de qué URL fallaron.links es un recuento, no una listapages informa cuántos enlaces seguibles se encontraron allí. Use extract_links en una página concreta si necesita las URL en sí.Ejemplos de solicitud
# The starting URL parameter is start_url, not url.
curl -X POST https://crawlforge.dev/api/v1/tools/crawl_deep \
-H "X-API-Key: cf_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"start_url": "https://example.com/docs",
"max_pages": 25,
"max_depth": 2,
"same_domain_only": true,
"crawl_delay": 1000,
"timeout": 30000
}'Ejemplo de respuesta
{ "success": true, "data": { "start_url": "https://example.com/docs", "pages_crawled": 12, "max_depth_reached": 2, "total_links_found": 184, "pages": [ { "url": "https://example.com/docs", "depth": 0, "title": "Documentation", "links": 24 }, { "url": "https://example.com/docs/quickstart", "depth": 1, "title": "Quickstart", "links": 18 }, { "url": "https://example.com/docs/api", "depth": 1, "title": "API Reference", "links": 31 } ], "crawl_stats": { "completed": true, "duration_ms": 8380, "pages_per_depth": { "0": 1, "1": 6, "2": 5 } } }, "credits_used": 4, "credits_remaining": 996, "processing_time": 8420}data.pages_crawledPáginas realmente visitadas y analizadas. Menor que max_pages cuando hubo páginas fallidas o el sitio se quedó sin enlaces alcanzables.data.max_depth_reachedNivel más profundo alcanzado. Un valor menor que max_depth significa que el rastreo agotó el sitio o llegó antes a max_pages.data.total_links_foundSuma de los recuentos de enlaces por página. Cuenta duplicados entre páginas, así que no es un recuento de URL distintas.data.pagesUna entrada por página visitada, en orden de visita: en anchura, primero la profundidad 0 y luego toda la profundidad 1.data.pages.linksNúmero de enlaces seguibles encontrados en esa página, no las URL. Use extract_links para obtener la lista.data.crawl_stats.duration_msTiempo dedicado al rastreo, en milisegundos. Algo menor que processing_time del sobre, que además incluye el manejo de la solicitud.data.crawl_stats.pages_per_depthCuántas páginas se visitaron en cada profundidad: la forma del sitio tal como se alcanza desde start_url.processing_timeTiempo total real del rastreo, en milisegundos.Manejo de errores
start_url ausente o inválida (400 VALIDATION_ERROR)
La causa más común es enviar url en lugar de start_url. Las claves desconocidas se descartan, así que la solicitud llega sin ninguna URL inicial. El arreglo details nombra el campo que falla.
Parámetro fuera de rango (400 VALIDATION_ERROR)
max_pages debe estar entre 1 y 100, max_depth entre 1 y 5, crawl_delay entre 0 y 5000, y timeout entre 1000 y 60000. Los valores fuera de esos límites se rechazan en lugar de ajustarse.
start_url no permitida por robots.txt (403 ROBOTS_DISALLOWED)
El robots.txt del destino no permite CrawlForge para esa URL. No se descarga nada ni se cobran credits. Use respect_robots: false —o su alias antiguo respect_robots_txt— solo cuando tenga su propio acuerdo con el sitio: la anulación queda registrada en su API key. La anulación no alcanza a un host incluido en la lista de exclusión permanente de CrawlForge, que se rechaza sea cual sea el valor de respect_robots.
El rastreo falló (500 TOOL_ERROR)
Un fallo inesperado durante el rastreo. Los fallos de páginas individuales no provocan esto (se omiten en silencio), así que un 500 significa que el rastreo en sí no pudo continuar.
max_pages es la palanca que importa. Limita el trabajo directamente y, dado que timeout se reparte entre esas páginas, un max_pages alto con un timeout bajo deja muy poco tiempo a cada página y aumenta silenciosamente cuántas fallan.Costo en credits
Desglose de costos:
Cualquier rastreo, de 1 a 100 páginas: 4 credits
Recomendaciones por plan:
Plan Free: 1.000 credits de prueba únicos = 250 rastreos
Plan Hobby: 5.000 credits/mes = 1.250 rastreos ($19/mes)
Plan Professional: 50.000 credits/mes = 12.500 rastreos ($99/mes)
Como el costo es fijo, prefiera un rastreo con un max_pages alto antes que varios rastreos pequeños del mismo sitio.