InvestigaciónMultifuente10 credits

deep_research

Plantee una pregunta y la herramienta ejecuta varias búsquedas web, descarga los resultados más prometedores, puntúa cada pasaje frente a su consulta y devuelve los más sólidos, cada uno con la URL y el título de la página de la que procede.

Casos de uso

Responder una pregunta con citas adjuntas

Cada hallazgo lleva su source_url, de modo que cada afirmación puede rastrearse hasta la página de la que se tomó.

Revisar qué dicen varias fuentes sobre un tema

Una sola llamada ejecuta varias consultas de búsqueda y extrae de hasta 10 fuentes distintas, en lugar de leer una página cada vez.

Fundamentar un prompt de LLM en material descargado

Los hallazgos son pasajes textuales, no paráfrasis, así que puede pasarlos a su propio modelo como contexto sin un salto adicional por el resumen de otra persona.

Restringir la investigación a fuentes de confianza

research_scope.domains limita la búsqueda a un máximo de 10 dominios: útil para investigación regulatoria, de proveedores o de documentación interna.

Endpoint

POST/api/v1/tools/deep_research

Auth Required

1 solicitud/s en el plan Free

10 credits

Parameters

El parámetro de la consulta se llama research_query, no topic ni query, y debe tener al menos 10 caracteres. Las claves desconocidas se descartan en silencio, así que enviar topic produce un 400 por falta de research_query.

Name	Type	Required	Default	Description
research_query	string	Required	-	La pregunta a investigar. Mínimo 10 caracteres. Formúlela como una pregunta o una afirmación concreta: el texto se usa tanto para ejecutar las búsquedas como para puntuar los pasajes, así que una consulta precisa clasifica mejor que una palabra clave suelta. Example: What are the tradeoffs of edge caching for API responses?
research_scope	object	Optional	-	Controles opcionales sobre la amplitud y la actualidad de la investigación.
max_sources	number	Optional	-	Anula el número de fuentes implícito en `depth_level`, de 1 a 10. Tiene prioridad cuando se indican ambos. Example: 8
respect_robots	boolean	Optional	true	Respeta el robots.txt de cada sitio de origen. Con el valor `true`, un resultado de búsqueda cuyo robots.txt no permita a `CrawlForge` no se descarga: permanece en el conjunto de fuentes con `fetched: false` y solo su fragmento de búsqueda, y el motivo se indica en `warnings` en lugar de devolver un 403. El coste fijo en credits no cambia. Póngalo en `false` solo para destinos con los que tenga su propio acuerdo: la anulación queda registrada en su API key y no alcanza a un host incluido en la lista de exclusión permanente de CrawlForge. Example: true
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

La síntesis en la API REST alojada es extractiva, no generativa. No interviene ningún LLM: los hallazgos y el resumen son pasajes seleccionados y clasificados de las páginas descargadas, devueltos textualmente. La propia respuesta lo indica en methodology.llm_used: false. Para una síntesis redactada por un LLM, use el servidor MCP de CrawlForge.

Cómo funciona una investigación

Cuatro etapas, todas dentro de una única solicitud.

1. Expandir y buscar

Su consulta se convierte en varias consultas de búsqueda, ejecutadas contra la Brave Search API. Las consultas exactas utilizadas se devuelven en methodology.queries_run, y el backend que las ejecutó, en methodology.search_backend.

2. Seleccionar fuentes

Los resultados se deduplican y se conservan los mejores candidatos, tantos como permitan depth_level o max_sources. methodology.sources_considered informa cuántos se vieron antes del corte.

3. Descargar y puntuar

Cada fuente conservada se descarga y se divide en pasajes, y cada pasaje se puntúa frente a los términos de su consulta. Las fuentes que no se pueden descargar permanecen en sources con fetched: false.

4. Clasificar y devolver

Los 10 pasajes con mayor puntuación se convierten en key_findings, cada uno truncado a 600 caracteres y etiquetado con la URL de la que procede.

relevance_score es una puntuación de coincidencia de términos frente a su consulta, no un juicio sobre la exactitud de los hechos ni sobre la credibilidad de la fuente. Una puntuación alta significa que el pasaje coincide con lo que preguntó, nada más. Consulte source_url antes de fiarse de un hallazgo.

Ejemplos de solicitud

terminalBash

# The query parameter is research_query, not topic. Minimum 10 characters.
curl -X POST https://crawlforge.dev/api/v1/tools/deep_research \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "research_query": "What are the tradeoffs of edge caching for API responses?",
    "research_scope": {
      "depth_level": "deep",
      "time_range": "year",
      "language": "en"
    },
    "max_sources": 8
  }'

# Restrict the search to sources you already trust
curl -X POST https://crawlforge.dev/api/v1/tools/deep_research \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "research_query": "What does the EU AI Act require for general-purpose models?",
    "research_scope": {
      "domains": ["europa.eu", "eur-lex.europa.eu"]
    }
  }'

Ejemplo de respuesta

200 OK14,260ms

{
  "success": true,
  "data": {
    "research_query": "What are the tradeoffs of edge caching for API responses?",
    "methodology": {
      "queries_run": [
        "tradeoffs of edge caching for API responses",
        "edge caching API responses disadvantages",
        "CDN edge cache API latency consistency"
      ],
      "search_backend": "brave",
      "sources_considered": 27,
      "sources_fetched": 5,
      "synthesis": "extractive",
      "llm_used": false
    },
    "key_findings": [
      {
        "text": "Edge caching cuts round-trip latency by serving from a point of presence near the client, but it introduces a consistency window: until the TTL expires or an explicit purge lands, different regions can serve different versions of the same resource.",
        "source_url": "https://example.com/engineering/edge-caching",
        "source_title": "Edge caching in practice",
        "relevance_score": 0.874
      },
      {
        "text": "Purge propagation is the operational cost most teams underestimate. A global invalidation is not instantaneous, and designs that assume it is will read stale data during the propagation window.",
        "source_url": "https://example.org/cdn-invalidation",
        "source_title": "CDN invalidation strategies",
        "relevance_score": 0.791
      }
    ],
    "sources": [
      {
        "url": "https://example.com/engineering/edge-caching",
        "title": "Edge caching in practice",
        "snippet": "How edge caching changes the latency and consistency profile of an API...",
        "fetched": true,
        "domain": "example.com"
      },
      {
        "url": "https://example.net/blocked-article",
        "title": "Caching at the edge",
        "snippet": "An overview of edge caching patterns...",
        "fetched": false,
        "domain": "example.net"
      }
    ],
    "summary": "Edge caching trades consistency for latency. The dominant operational cost is purge propagation, and the dominant design question is which endpoints tolerate a staleness window.",
    "notes": "Synthesis is extractive (no LLM on the hosted API). For LLM-synthesized deep research, use the CrawlForge MCP server.",
    "researched_at": "2026-08-26T14:30:00.000Z"
  },
  "credits_used": 10,
  "credits_remaining": 990,
  "processing_time": 14260
}

Field Descriptions

data.methodology.queries_runLas búsquedas realmente realizadas, expandidas a partir de su consulta. Útil para juzgar si la ejecución entendió la pregunta.

data.methodology.sources_consideredResultados de búsqueda vistos antes de la selección; sources_fetched indica cuántos se descargaron después.

data.methodology.llm_usedSiempre false en la API REST alojada: la síntesis es extractiva.

data.key_findingsHasta 10 pasajes, primero los de mayor puntuación, cada uno truncado a 600 caracteres.

data.key_findings.source_urlLa página de la que se tomó textualmente el pasaje: esta es la cita.

data.key_findings.relevance_scorePuntuación de coincidencia de términos frente a su consulta, redondeada a 3 decimales. No es una señal de credibilidad.

data.sources.fetchedFalse cuando no se pudo descargar la página. Sigue apareciendo aquí, pero no aportó ningún hallazgo.

data.summaryCompuesto a partir de los pasajes mejor clasificados, no redactado por un modelo.

processing_timeLas investigaciones son lentas: buscar y descargar varias páginas suele tardar entre 10 y 20 segundos.

Manejo de errores

Falta research_query (400 VALIDATION_ERROR)

Suele deberse a enviar topic o query en su lugar. Las claves desconocidas se descartan, así que la solicitud llega sin ninguna consulta.

Consulta demasiado corta (400 VALIDATION_ERROR)

research_query debe tener al menos 10 caracteres. Una palabra clave suelta se rechaza y, en general, es una mala consulta: los pasajes se puntúan frente a estos términos.

Backend de búsqueda inalcanzable (502 RESEARCH_SEARCH_UNAVAILABLE)

No se pudo contactar con el proveedor de búsqueda. No se cobran credits.

La búsqueda falló (502 RESEARCH_SEARCH_FAILED)

El proveedor de búsqueda respondió con un error, normalmente un límite de cuota. No se cobran credits.

No permitido por robots.txt (sin error: la fuente no se descarga)

Un resultado de búsqueda que robots.txt no permite a CrawlForge no se descarga, pero permanece en el conjunto de fuentes con fetched: false y su fragmento de búsqueda, y warnings lo indica: la ejecución no devuelve ningún 403 y el número de fuentes no cambia. Establezca respect_robots: false para anularlo en destinos con los que tenga su propio acuerdo: la anulación queda registrada en su API key y no alcanza a un host incluido en la lista de exclusión permanente de CrawlForge.

Cómo obtener mejores hallazgos:

La puntuación es coincidencia de términos frente a research_query, así que la consulta cumple doble función: entrada de búsqueda y clave de clasificación. Una pregunta específica con términos distintivos supera a una amplia, y research_scope.domains es más eficaz que alargar la consulta cuando ya sabe en qué fuentes confía.

Costo en credits

10 credits

10 credits por solicitud

10 credits fijos sin importar el depth_level ni cuántas fuentes se descarguen: una ejecución comprehensive sobre 10 fuentes cuesta lo mismo que una surface sobre 3. Las llamadas fallidas, incluidos ambos errores del backend de búsqueda, no se cobran.

Desglose de costos:

Cualquier investigación, de 3 a 10 fuentes: 10 credits

Recomendaciones por plan:

Plan Free: 1.000 credits de prueba únicos = 100 investigaciones

Plan Hobby: 5.000 credits/mes = 500 investigaciones ($19/mes)

Plan Professional: 100.000 credits/mes = 10.000 investigaciones ($99/mes)

Como el costo es fijo, no hay ahorro en ejecutar surface: use deep o comprehensive salvo que necesite rapidez.

Herramientas relacionadas

search_web

Resultados de búsqueda clasificados sin descargar las páginas (5 credits)

extract_content

Extraiga el cuerpo legible de una fuente que ya eligió (2 credits)

summarize_content

Condense una sola página en lugar de investigar una pregunta (4 credits)

agent

Investigación autónoma de varios pasos con planificación por LLM (8 credits)

¿Listo para probar deep_research? Regístrese gratis y obtenga 1.000 credits: suficiente para 100 investigaciones.