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
/api/v1/tools/deep_researchParameters
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 |
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.
methodology.queries_run.depth_level o max_sources. methodology.sources_considered informa cuántos se vieron antes del corte.sources con fetched: false.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
# 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
{ "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": "google_cse", "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}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.
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
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: 50.000 credits/mes = 5.000 investigaciones ($99/mes)
Como el costo es fijo, no hay ahorro en ejecutar surface: use deep o comprehensive salvo que necesite rapidez.