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

POST/api/v1/tools/crawl_deep

Auth Required

1 solicitud/s en el plan Free

4 credits

Parameters

El parámetro de la URL inicial se llama 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
max_inline_chars	number	Optional	40000	Tamaño máximo del resultado que se devuelve en línea, en caracteres de su JSON (de 1.000 a 10.000.000). Por encima, la respuesta incluye `preview` (los primeros `max_inline_chars` caracteres del JSON formateado), `result_handle`, `total_chars`, `truncated: true` y `expires_at`, y [read_result](/docs/api-reference/tools/read-result) lee el resto por 1 credit por llamada. Los resultados almacenados se conservan 1 hora. Example: 40000
redact_pii	boolean \| object	Optional	false	Elimine los datos personales del texto que devuelve esta llamada, antes de que el resultado se almacene o se envíe de vuelta. Se aplica a todas las páginas que devuelve el rastreo. `true` es la forma abreviada de `{ mode: "fast" }`: las cuatro clases de expresiones regulares, etiquetadas. Siempre que pida redacción, la respuesta lleva `redaction: { entities, count, mode }` dentro de `data`, incluso cuando no hubo coincidencias (`count: 0`), de modo que «no se encontró nada» nunca se confunde con «se ignoró el parámetro»; una clase sin coincidencias se omite en lugar de informarse como `0`. La redacción se ejecuta antes de almacenar el resultado, así que un resultado grande que se lea después con [read_result](/docs/api-reference/tools/read-result) ya viene redactado. Dos límites deliberados: las direcciones (`url`, `link`, `href`, `canonical_url`) nunca se redactan, y los contadores derivados del texto (`content_length`, `word_count`, `character_count`) lo describen tal como se extrajo, antes de la redacción. Example: true

Las solicitudes se identifican con el token de producto 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.

En anchura, no en profundidad

Todas las páginas de profundidad 1 se visitan antes que cualquier página de profundidad 2. Con un max_pages bajo obtiene un mapa amplio y superficial en lugar de una sola rama profunda.

Las páginas fallidas se enumeran en errors

Si una página agota el tiempo, no se puede alcanzar o responde con un error HTTP, se deja fuera de pages, se enumera en errors con su URL, su profundidad y el motivo, y el rastreo continúa. Cada una consume igualmente una página del presupuesto de max_pages, así que pages_attempted es pages_crawled más error_count.

links es un recuento, no una lista

Cada entrada de pages informa cuántos enlaces seguibles se encontraron allí. Use extract_links en una página concreta si necesita las URL en sí.

No se ejecuta JavaScript

Las páginas se descargan por HTTP y se analizan como HTML sin procesar, así que los enlaces generados en el cliente son invisibles y sus páginas nunca se descubren.

Ejemplos de solicitud

terminalBash

# 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

200 OK8,420ms

{
  "success": true,
  "data": {
    "start_url": "https://example.com/docs",
    "pages_attempted": 13,
    "pages_crawled": 12,
    "error_count": 1,
    "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
      }
    ],
    "errors": [
      {
        "url": "https://example.com/docs/legacy",
        "depth": 2,
        "error": "HTTP 404"
      }
    ],
    "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
}

Field Descriptions

data.pages_attemptedURL que el rastreo solicitó: pages_crawled más error_count.

data.pages_crawledPáginas obtenidas y analizadas, una entrada por cada una en pages. Menor que max_pages cuando hubo páginas fallidas o el sitio se quedó sin enlaces alcanzables.

data.error_countURL que se solicitaron y no produjeron una página, una entrada por cada una en errors.

data.errorsUna entrada por URL fallida: url, depth, error (el motivo, como "HTTP 404") y code cuando se conoce, como FETCH_TIMEOUT o FETCH_FAILED.

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 enumeran en errors), así que un 500 significa que el rastreo en sí no pudo continuar.

Cómo controlar el costo y la duración:

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

4 credits

4 credits por solicitud

4 credits fijos por llamada, sin importar cuántas páginas visite el rastreo: rastrear 100 páginas cuesta lo mismo que rastrear 5. Las llamadas fallidas no se cobran.

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: 100.000 credits/mes = 25.000 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.

Herramientas relacionadas

map_site

Descubra URL sin visitar cada página (2 credits)

extract_links

Obtenga las URL reales de los enlaces de una página (1 credit)

batch_scrape

Extraiga contenido de las URL que descubrió un rastreo (5 credits por URL)

scrape

Extracción completa de contenido de una sola página (2 credits)

¿Listo para probar crawl_deep? Regístrese gratis y obtenga 1.000 credits para mapear su primer sitio.