deep_research
Berikan satu soalan dan ia menjalankan beberapa carian web, mengambil hasil yang paling menjanjikan, memberi skor kepada setiap petikan berbanding pertanyaan anda, dan memulangkan yang terkuat — setiap satu membawa URL dan tajuk halaman asalnya.
Kes Penggunaan
Jawab satu soalan dengan sitasi dilampirkan
Setiap penemuan membawa source_urlnya, jadi setiap dakwaan boleh dijejaki kembali kepada halaman tempat ia diambil.
Tinjau apa kata beberapa sumber tentang satu topik
Satu panggilan menjalankan beberapa pertanyaan carian dan menarik daripada sehingga 10 sumber berbeza, bukannya membaca satu halaman pada satu masa.
Sandarkan gesaan LLM pada bahan yang diambil
Penemuan ialah petikan kata demi kata, bukan parafrasa, jadi ia boleh dihantar kepada model anda sendiri sebagai konteks tanpa satu lagi lompatan melalui ringkasan orang lain.
Hadkan penyelidikan kepada sumber yang anda percayai
research_scope.domains mengehadkan carian kepada sebanyak 10 domain — berguna untuk penyelidikan kawal selia, vendor atau dokumentasi dalaman.
Endpoint
/api/v1/tools/deep_researchParameters
research_query, bukan topic atau query, dan mesti sekurang-kurangnya 10 aksara. Kunci yang tidak dikenali dibuang secara senyap, jadi menghantar topic menghasilkan 400 kerana research_query tiada.| Name | Type | Required | Default | Description |
|---|---|---|---|---|
research_query | string | Required | - | Soalan yang hendak diselidik. Minimum 10 aksara. Ungkapkannya sebagai soalan atau dakwaan khusus — perkataannya digunakan untuk menjalankan carian dan juga untuk memberi skor kepada petikan, jadi pertanyaan yang tepat menyusun lebih baik daripada kata kunci tunggal. Example: What are the tradeoffs of edge caching for API responses? |
research_scope | object | Optional | - | Kawalan pilihan ke atas seluas dan sebaharu mana penyelidikan itu. |
max_sources | number | Optional | - | Batalkan bilangan sumber yang tersirat daripada `depth_level`, 1-10. Ia diutamakan apabila kedua-duanya ditetapkan. Example: 8 |
respect_robots | boolean | Optional | true | Hormati robots.txt setiap tapak sumber. Dibiarkan pada `true`, hasil carian yang robots.txt-nya melarang `CrawlForge` tidak diambil — ia kekal dalam set sumber dengan `fetched: false` dan hanya petikan cariannya, dan sebabnya dinamakan dalam `warnings` dan bukannya dikembalikan sebagai 403. Kos credits rata itu tidak berubah. Tetapkan kepada `false` hanya untuk sasaran yang anda mempunyai perjanjian sendiri dengannya — tindakan mengatasi itu direkodkan pada API key anda dan tidak sampai kepada hos yang berada dalam senarai penarikan diri kekal CrawlForge. Example: true |
methodology.llm_used: false. Untuk sintesis yang ditulis LLM, gunakan pelayan MCP CrawlForge.Bagaimana satu larian penyelidikan berjalan
Empat peringkat, semuanya di dalam satu permintaan.
methodology.queries_run.depth_level atau max_sources. methodology.sources_considered melaporkan berapa banyak dilihat sebelum pemotongan.sources dengan fetched: false.key_findings, setiap satu dipangkas kepada 600 aksara dan ditandakan dengan URL asalnya.relevance_score ialah skor pertindihan terma berbanding pertanyaan anda, bukan pertimbangan tentang ketepatan fakta atau kredibiliti sumber. Skor tinggi bermakna petikan itu sepadan dengan apa yang anda tanya — tidak lebih. Baca source_url sebelum bergantung pada sesuatu penemuan.Contoh Permintaan
# 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"]
}
}'Contoh Respons
{ "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_runCarian yang benar-benar dilakukan, dikembangkan daripada pertanyaan anda. Berguna untuk menilai sama ada larian itu memahami soalan.data.methodology.sources_consideredHasil carian yang dilihat sebelum pemilihan; sources_fetched ialah berapa banyak kemudiannya diambil.data.methodology.llm_usedSentiasa false pada API REST terhos — sintesis bersifat ekstraktif.data.key_findingsSehingga 10 petikan, berskor tertinggi dahulu, setiap satu dipangkas kepada 600 aksara.data.key_findings.source_urlHalaman tempat petikan itu diambil kata demi kata — inilah sitasinya.data.key_findings.relevance_scoreSkor pertindihan terma berbanding pertanyaan anda, dibundarkan kepada 3 titik perpuluhan. Bukan isyarat kredibiliti.data.sources.fetchedFalse apabila halaman itu tidak dapat diambil. Ia masih muncul di sini, tetapi tidak menyumbang sebarang penemuan.data.summaryDihimpun daripada petikan berkedudukan teratas, bukan ditulis oleh model.processing_timeLarian penyelidikan adalah perlahan — mencari dan mengambil beberapa halaman lazimnya mengambil 10-20 saat.Pengendalian Ralat
research_query tiada (400 VALIDATION_ERROR)
Lazimnya berpunca daripada menghantar topic atau query sebaliknya. Kunci yang tidak dikenali dibuang, jadi permintaan itu tiba tanpa sebarang pertanyaan.
Pertanyaan terlalu pendek (400 VALIDATION_ERROR)
research_query mesti sekurang-kurangnya 10 aksara. Kata kunci tunggal ditolak dan, secara amnya, merupakan pertanyaan yang lemah — petikan diberi skor berbanding terma ini.
Bahagian belakang carian tidak dapat dicapai (502 RESEARCH_SEARCH_UNAVAILABLE)
Penyedia carian huluan tidak dapat dihubungi. Tiada credits dicaj.
Carian gagal (502 RESEARCH_SEARCH_FAILED)
Penyedia carian membalas dengan ralat, paling kerap had kuota. Tiada credits dicaj.
Dilarang oleh robots.txt (bukan ralat — sumber itu tidak diambil)
Hasil carian yang dilarang oleh robots.txt untuk CrawlForge tidak diambil, tetapi ia kekal dalam set sumber dengan fetched: false dan petikan cariannya, dan warnings menamakannya — jadi larian itu tidak mengembalikan sebarang 403 dan bilangan sumber tidak berubah. Tetapkan respect_robots: false untuk mengatasinya bagi sasaran yang anda mempunyai perjanjian sendiri dengannya — tindakan mengatasi itu direkodkan pada API key anda, dan ia tidak sampai kepada hos yang berada dalam senarai penarikan diri kekal CrawlForge.
research_query, jadi pertanyaan itu berperanan dua kali: sebagai input carian dan sebagai kunci penyusunan. Soalan khusus dengan terma tersendiri mengatasi soalan yang luas — dan research_scope.domains lebih berkesan daripada pertanyaan yang lebih panjang apabila anda sudah tahu sumber mana yang anda percayai.Kos credits
depth_level atau berapa banyak sumber diambil — larian comprehensive ke atas 10 sumber berharga sama seperti larian surface ke atas 3. Panggilan gagal, termasuk kedua-dua ralat bahagian belakang carian, tidak dicaj.Pecahan Kos:
Sebarang larian penyelidikan, 3 hingga 10 sumber: 10 credits
Cadangan Pelan:
Pelan Free: 1,000 credits percubaan sekali sahaja = 100 larian penyelidikan
Pelan Hobby: 5,000 credits/bulan = 500 larian penyelidikan ($19/bulan)
Pelan Professional: 50,000 credits/bulan = 5,000 larian penyelidikan ($99/bulan)
Kerana kosnya rata, tiada penjimatan dalam menjalankan surface — gunakan deep atau comprehensive melainkan anda memerlukan kelajuan.