CarianBrave Search API5 credits

search_web

Indeks web langsung, sebagai JSON. Hasil datang daripada indeks web bebas Brave Search API. Setiap hasil membawa tajuk, URL, cebisan dan salinan bersorot cebisan itu, di samping blok metadata yang menyatakan tempoh carian itu. Penapis tapak dan jenis fail digunakan sebagai operator carian; bahasa, kebaruan dan carian selamat dihantar sebagai penapis carian.

Kes Penggunaan

Saluran Penyelidikan

Cari sumber bagi sesuatu topik, kemudian suapkan URL itu terus ke batch_scrape atau extract_content.

Carian Terhad kepada Tapak

Tetapkan site untuk mencari dalam satu domain — pengganti kotak carian tapak yang tidak wujud atau berfungsi dengan buruk.

Pemburuan Dokumen

Gabungkan file_type dengan pertanyaan untuk mencari PDF, hamparan atau dek slaid tentang sesuatu subjek.

Pemantauan Kebaruan

Hadkan kepada hari atau minggu lepas dengan time_range untuk menangkap liputan baharu tentang sesuatu topik atau jenama.

Penemuan Persaingan

Lihat halaman yang ditonjolkan oleh carian web langsung bagi istilah yang anda pentingkan. Untuk kedudukan Google anda yang tepat, gunakan serp_rank.

Pengukuhan Ejen

Berikan model hasil carian semasa untuk digunakan, dan bukannya bergantung pada apa yang dihafalnya.

Endpoint

POST/api/v1/tools/search_web

Auth Required

1 req/s pada pelan Free

5 credits

Parameters

limit menerima sehingga 100, tetapi satu permintaan mengembalikan paling banyak 10 hasil — limit yang lebih besar tidak gagal, ia hanya memberi anda 10. Halusuri selebihnya dengan offset, satu carian (dan 5 credits) setiap halaman. Hantar tepat satu daripada query atau queries: kelompok queries menjalankan satu carian bagi setiap pertanyaan, dan 5 credits × bilangan pertanyaan yang anda hantar — 50 bagi maksimum 10 — ialah unjuran, satu siling dan bukan cajnya. Hanya pertanyaan yang mengembalikan hasil yang dicaj.

Name	Type	Required	Default	Description
query	string	Optional	-	Istilah carian. Operator seperti `site:`, `filetype:` dan frasa dalam tanda petik berfungsi seperti dalam kotak carian, dan `site` serta `file_type` ditambah sebagai operator di atasnya. Hantar tepat satu daripada `query` atau `queries`. Example: mcp server for web scraping
queries	string[]	Optional	-	Antara 1 hingga 10 pertanyaan carian untuk dijalankan dalam satu panggilan, sebagai ganti `query`. Setiap satu menjalani saluran yang sama seperti carian tunggal, dan muatannya kembali dalam `results_by_query` — satu senarai mengikut susunan anda menghantarnya, satu entri bagi setiap pertanyaan yang membawa `query` miliknya sendiri berserta medan carian itu, atau `query` dan `error` apabila carian itu gagal. `queries` mengembalikan input anda sebagaimana adanya dan `count` ialah panjangnya. Satu panggilan `search_web` berharga 5 credits bagi setiap pertanyaan yang mengembalikan hasil — satu `query` tunggal berharga 5, dan kelompok `queries` diunjurkan pada 5 × bilangan pertanyaan yang dihantar, iaitu satu siling: setiap pertanyaan yang gagal tidak dicaj, jadi kelompok yang tiada satu pun berjaya tidak berharga apa-apa. Pertanyaan yang diulang dalam senarai itu berjalan dua kali dan dicaj dua kali apabila kedua-dua larian mengembalikan hasil. Kelompok yang tiada satu pun berjaya tetap 200 yang membawa sampul biasa: `count` sebagaimana dihantar, satu entri `{ query, error }` bagi setiap pertanyaan, dan `credits_used: 0`. Hantar tepat satu daripada `query` atau `queries` — kedua-duanya, atau tiada satu pun, ialah 400. Example: ["mcp server for web scraping", "model context protocol tools"]
limit	number	Optional	10	Hasil untuk dikembalikan, 1-100 — tetapi satu permintaan dihadkan kepada 10, jadi apa-apa melebihi 10 berkelakuan sebagai 10. Example: 10
offset	number	Optional	0	Indeks berasaskan sifar bagi hasil pertama. Gunakan 10, 20, 30 untuk berhalaman, sehingga 90: hasil selepas yang ke-100 tidak tersedia, dan halaman di luarnya kembali dengan tatasusunan `results` yang kosong. Setiap halaman ialah carian berasingan dan berharga 5 credits. Example: 10
lang	string	Optional	-	Utamakan dokumen dalam satu bahasa, sebagai kod ISO 639-1; bentuk serantau seperti `zh-TW` dan `pt-BR` juga diterima. Ia satu keutamaan, bukan penapis ketat, jadi halaman dalam bahasa lain masih boleh muncul, dan kod yang tidak disokong oleh bahagian belakang carian digugurkan dan bukannya menggagalkan carian. Dikembalikan dalam `search_metadata.lang`, yang lalai kepada `en` apabila anda meninggalkannya. Example: es
site	string	Optional	-	Hadkan kepada satu domain. Ditambah pada pertanyaan anda sebagai `site:<domain>`, jadi ia berkelakuan sama seperti menaipnya. Example: docs.anthropic.com
safe_search	boolean	Optional	-	Hidupkan penapisan carian selamat yang ketat. Dimatikan melainkan anda menetapkannya. Example: true
time_range	string	Optional	-	Hadkan mengikut kebaruan: `day`, `week`, `month`, `year` atau `all`. `all` tidak mengenakan sekatan, dan ia juga nilai lalai. Example: week
file_type	string	Optional	-	Hadkan kepada satu sambungan fail. Ditambah sebagai `filetype:<ext>`, jadi `pdf`, `xlsx` dan `pptx` semuanya berfungsi. Example: pdf
redact_pii	boolean \| object	Optional	false	Buang data peribadi daripada teks yang dikembalikan oleh panggilan ini, sebelum hasilnya disimpan atau dihantar balik. Terpakai pada tajuk dan cebisan yang dikembalikan oleh carian; `query` yang anda hantar dikembalikan sebagaimana adanya. `true` ialah singkatan bagi `{ mode: "fast" }` — keempat-empat kelas regex, bertag. Setiap kali anda meminta penyuntingan, respons membawa `redaction: { entities, count, mode }` di dalam `data`, walaupun tiada apa-apa yang sepadan (`count: 0`), jadi "tiada apa-apa ditemui" tidak pernah disalah anggap sebagai "parameter itu diabaikan"; kelas tanpa padanan ditinggalkan dan bukan dilaporkan sebagai `0`. Penyuntingan berjalan sebelum hasil itu disimpan, jadi hasil besar yang dibaca kemudian dengan [read_result](/docs/api-reference/tools/read-result) sudah pun disunting. Dua batas yang disengajakan: alamat (`url`, `link`, `href`, `canonical_url`) tidak pernah disunting, dan kiraan yang diperoleh daripada teks (`content_length`, `word_count`, `character_count`) menggambarkan teks itu sebagaimana ia diekstrak, sebelum penyuntingan. Example: true
max_inline_chars	number	Optional	40000	Hasil terbesar yang dikembalikan sebaris, dalam aksara JSON-nya (1,000-10,000,000). Melebihinya, respons membawa `preview` (`max_inline_chars` aksara pertama JSON yang diformat), `result_handle`, `total_chars`, `truncated: true` dan `expires_at`, dan [read_result](/docs/api-reference/tools/read-result) membaca selebihnya dengan 1 credit setiap panggilan. Hasil tersimpan disimpan selama 1 jam. Example: 40000

Carian Berkelompok

Hantar queries dan bukan query untuk menjalankan sehingga 10 carian dalam satu panggilan. Setiap pertanyaan ialah carian tunggal yang sama seperti panggilan query — API ini tidak mengembangkan pertanyaan, tidak menggunakan cache, tidak menyahduakan dan tidak menyusun semula keputusan — dan setiap pertanyaan yang mengembalikan keputusan dicaj 5 credits.

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "mcp server for web scraping",
      "model context protocol tools"
    ],
    "limit": 10,
    "redact_pii": true
  }'

Respons Berkelompok

results_by_query ialah satu senarai mengikut susunan anda menghantar pertanyaan itu, satu entri bagi setiap pertanyaan, jadi pertanyaan yang diulang muncul dua kali. Pertanyaan yang gagal membawa error menggantikan hasilnya dan tidak dicaj; panggilan itu mengembalikan 200 dalam kedua-dua keadaan, termasuk apabila setiap pertanyaan gagal, jadi credits_used ialah bilangan yang benar-benar berjaya didarab 5. Panggilan query tunggal tidak berubah: queries, count dan results_by_query tidak muncul padanya.

response.jsonJson

{
  "success": true,
  "data": {
    "queries": ["mcp server for web scraping", "model context protocol tools"],
    "count": 2,
    "results_by_query": [
      {
        "query": "mcp server for web scraping",
        "search_metadata": { "total_results": null, "results_returned": 10 },
        "results": [
          {
            "title": "CrawlForge MCP Server",
            "url": "https://www.crawlforge.dev/",
            "snippet": "Write to <EMAIL> for access."
          }
        ]
      },
      {
        "query": "model context protocol tools",
        "error": "Search request timeout"
      }
    ],
    "redaction": { "entities": { "EMAIL": 1 }, "count": 1, "mode": "fast" }
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 720
}

Contoh Permintaan

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mcp server for web scraping",
    "limit": 10,
    "time_range": "month",
    "safe_search": true
  }'

Contoh Respons

200 OK460ms

{
  "success": true,
  "data": {
    "query": "mcp server for web scraping",
    "search_metadata": {
      "total_results": null,
      "results_returned": 1,
      "offset": 0,
      "search_time": 0.312,
      "lang": "en",
      "safe_search": false,
      "time_range": "month",
      "site": null,
      "file_type": null
    },
    "results": [
      {
        "title": "CrawlForge MCP Server — 31 web tools for Claude",
        "url": "https://www.crawlforge.dev/",
        "snippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "displayLink": "www.crawlforge.dev",
        "formattedUrl": "https://www.crawlforge.dev/",
        "htmlSnippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "htmlTitle": "CrawlForge MCP Server — 31 web tools for Claude",
        "pagemap": {
          "cse_thumbnail": [
            {
              "src": "https://imgs.search.brave.com/example-thumbnail"
            }
          ],
          "metatags": [
            {
              "article:published_time": "2026-10-01T00:00:00"
            }
          ]
        }
      }
    ],
    "spelling_correction": null,
    "related_searches": []
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 460
}

Field Descriptions

data.queryPertanyaan yang dicari, sebagaimana anda menghantarnya, tanpa operator `site` dan `file_type`

data.search_metadata.total_results`null`: bahagian belakang carian tidak melaporkan jumlah kiraan padanan. Berhalaman dengan `offset` sehingga `results_returned` ialah 0

data.search_metadata.results_returnedPanjang `results` — paling banyak 10

data.search_metadata.search_timeSaat yang diambil oleh carian hulu, diukur oleh CrawlForge. Bukan jumlah kependaman permintaan anda

data.results[].urlPautan destinasi. `formattedUrl` membawa alamat yang sama

data.results[].htmlSnippetCebisan dengan penyorotan istilah `<strong>` enjin carian dikekalkan. Lepaskannya sebelum memaparkan

data.results[].pagemapButiran halaman apabila enjin carian memilikinya: `cse_thumbnail[0].src` (URL lakaran kecil) dan `metatags[0]['article:published_time']` (usia halaman). Tiada apabila kedua-duanya tiada

data.spelling_correctionPertanyaan yang dibetulkan apabila enjin carian mencari ejaan yang dibetulkan, atau `null`

data.related_searchesSentiasa tatasusunan kosong: bahagian belakang carian semasa tidak mengembalikan carian berkaitan. Dikekalkan supaya kod sedia ada tidak rosak

credits_used5 credits tetap setiap carian, apa jua `limit` yang anda minta

Pengendalian Ralat

Pertanyaan Tidak Sah (400 Bad Request)

VALIDATION_ERROR. query diperlukan dan tidak boleh kosong. Status yang sama meliputi limit di luar 1-100, offset negatif, atau time_range yang bukan salah satu daripada lima nilai yang diterima. Menghantar kedua-dua query dan queries, atau tiada satu pun, ialah 400 yang sama, begitu juga tatasusunan queries yang kosong atau melebihi 10 entri, objek redact_pii yang menamakan entiti yang tidak boleh disunting oleh API ini, atau redact_pii dengan mode: "model" — yang memerlukan LLM yang tidak dijalankan oleh API ini.

Carian Gagal (500 Internal Server Error)

TOOL_ERROR. Merangkumi ralat carian di hulu, had kadar di penyedia carian, dan tamat masa selepas 10 saat. Mesejnya menyatakan puncanya. Carian yang gagal tidak dicaj. Inilah laluan query tunggal: satu carian yang gagal memberi ralat seperti biasa. Kelompok queries tidak pernah sampai ke sini — pertanyaan yang gagal dilaporkan dalam entri results_by_query miliknya sendiri dan panggilan itu tetap mengembalikan 200, walaupun setiap pertanyaan gagal.

Nota:

Carian yang tidak sepadan dengan apa-apa mengembalikan 200 dengan tatasusunan results yang kosong — bukan ralat. Periksa results_returned dan bukannya bergantung pada kod status.

Kos Credit

5 credits

5 credits setiap carian

Satu carian ialah satu caj, sama ada ia mengembalikan 10 hasil atau tiada. Berhalaman dengan offset bermakna satu lagi carian, jadi sepuluh halaman berharga 50 credits. Carian yang gagal tidak dicaj. Satu panggilan search_web berharga 5 credits bagi setiap pertanyaan yang mengembalikan hasil — satu query tunggal berharga 5, dan kelompok queries diunjurkan pada 5 × bilangan pertanyaan yang dihantar, iaitu satu siling: setiap pertanyaan yang gagal tidak dicaj, jadi kelompok yang tiada satu pun berjaya tidak berharga apa-apa. Sepuluh pertanyaan dalam satu panggilan diunjurkan pada 50 dan berharga 50 hanya jika kesepuluh-sepuluhnya mengembalikan hasil. redact_pii dalam mod fast lalainya tidak menambah apa-apa.

Apa yang Disertakan:

Indeks web langsung (Brave Search API), bukan salinan cache

Tajuk, URL, cebisan dan salinan bersorot cebisan itu

Masa carian, serta lakaran kecil dan usia halaman apabila tersedia

Penapis site, file_type, lang, time_range dan carian selamat

Pembetulan ejaan apabila enjin carian menggunakannya

Cadangan Pelan:

Free Plan: 1,000 credits percubaan sekali sahaja = 200 carian

Hobby Plan: 5,000 credits = 1,000 carian ($19/mo)

Professional Plan: 100,000 credits = 20,000 carian ($99/mo)