Cara Mendapatkan Kunci API Brave Search dan Menjalankan Kueri Pencarian Pertama Anda

Kunci API Brave memberikan Anda akses terprogram ke indeks web independen Brave: hasil yang sama yang disajikan Brave Search di peramban, dikembalikan dalam bentuk JSON yang dapat Anda masukkan ke dalam skrip, dasbor, atau agen AI. API Brave Search telah menjadi pilihan umum untuk memberikan agen akses web langsung; jika itu tujuan akhir Anda, panduan server Brave Search MCP menunjukkan bagaimana kunci tersebut terhubung ke Claude dan klien MCP lainnya. Postingan ini mencakup bagian sebelum itu: membuat akun, memilih paket, membuat kunci, dan mengirim kueri nyata dengan curl, Python, dan Apidog.

Semua yang di bawah ini berasal dari dokumentasi dasbor Brave sendiri per September 2026. Harga dan batasan dapat berubah, jadi anggap angka-angka ini sebagai gambaran sesaat dan periksa halaman-halaman yang ditautkan sebelum Anda membuat anggaran.

Yang Anda Butuhkan Sebelum Memulai

• Alamat email untuk akun dasbor.
• Kartu kredit. Brave mewajibkan satu kartu di setiap paket, termasuk tingkat kredit gratis, sebagai pemeriksaan anti-penipuan. FAQ di halaman paket menyatakan bahwa untuk paket gratis, kartu hanya digunakan untuk mengonfirmasi identitas Anda.
• curl, atau Python 3 dengan paket requests, untuk contoh baris perintah.
• Apidog, jika Anda ingin menyimpan kunci dengan aman dan mengubah permintaan menjadi tes yang dapat diulang. Ini opsional untuk panggilan pertama.

Langkah 1: Buat akun API Brave Search

Buka dasbor API Brave Search dan daftar dengan alamat email serta kata sandi. Brave akan mengirim tautan konfirmasi; klik tautan tersebut untuk memverifikasi alamat. Sampai Anda melakukannya, Anda tidak dapat mengaktifkan paket.

Dasbor ini terpisah dari peramban Brave atau login Brave Rewards apa pun, jadi akun peramban yang sudah ada tidak akan terbawa. Daftar baru.

Langkah 2: Pilih paket (tingkat gratis memiliki satu kendala)

Buka halaman Paket di dasbor. Per September 2026, halaman harga Brave mencantumkan opsi-opsi ini:

Untuk pencarian web, pilih Search. Kredit bulanan $5 mencakup sekitar 1.000 permintaan pencarian web sebelum Anda membayar apa pun, yang cukup untuk pengembangan dan beban kerja agen kecil. Penagihan bersifat prabayar: Anda membeli kredit di muka, dan kredit gratis bulanan diterapkan secara otomatis.

Kendalanya adalah kartu. Anda tidak dapat mengaktifkan paket apa pun, termasuk kredit gratis, tanpa memasukkan kartu. Jika Anda pernah melihat panduan lama yang menjelaskan paket gratis tanpa kartu dengan kuota kueri bulanan tetap, itu menjelaskan generasi harga Brave sebelumnya. Akun baru mendapatkan model kredit di atas.

Pilih paket dan masukkan detail kartu Anda. Paket akan langsung muncul sebagai aktif di dasbor.

Langkah 3: Buat kunci API

Dengan paket yang aktif, buka bagian Kunci API, klik “Tambah Kunci API”, dan berikan nama deskriptif pada kunci tersebut. Quickstart Brave menyarankan nama seperti “Aplikasi Produksi” atau “Pengembangan”. Satu kunci per lingkungan akan bermanfaat nanti, ketika Anda perlu mencabut satu kunci tanpa menyentuh yang lain.

Salin kunci dan simpan di tempat yang aman segera. Panduan autentikasi Brave secara tegas menyatakan di mana kunci itu tidak boleh disimpan: kode sisi klien, repositori publik, atau lokasi publik mana pun. Jika Anda baru mengenal cara kerja kredensial ini, panduan singkat tentang apa itu kunci API akan membahas model tersebut dalam beberapa menit.

Langkah 4: Kirim permintaan pencarian pertama Anda

Endpoint pencarian web adalah https://api.search.brave.com/res/v1/web/search. Setiap permintaan memerlukan kunci di header X-Subscription-Token. Perhatikan nama header: ini bukan Authorization: Bearer, dan mengirim kunci dengan cara tersebut akan gagal.

curl

curl "https://api.search.brave.com/res/v1/web/search?q=openapi+3.1+breaking+changes&count=5&freshness=py" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

count membatasi hasil per halaman (maks 20, default 20), offset mengelola halaman (berbasis 0, maks 9), dan freshness menyaring berdasarkan usia: pd, pw, pm, atau py untuk hari, minggu, bulan, atau tahun terakhir. Parameter berguna lainnya adalah country (kode dua huruf), search_lang, dan safesearch (off, moderate, atau strict; moderate adalah default).

Python

import os
import requests

url = "https://api.search.brave.com/res/v1/web/search"
headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": os.environ["BRAVE_API_KEY"],
}
params = {"q": "openapi 3.1 breaking changes", "count": 5, "freshness": "py"}

resp = requests.get(url, headers=headers, params=params, timeout=10)
resp.raise_for_status()
data = resp.json()

for hit in data["web"]["results"]:
    print(hit["title"])
    print(hit["url"])
    print(hit["description"][:120], "\n")

Respons membawa objek query (dengan original dan boolean more_results_available untuk penomoran halaman) serta array web.results. Setiap hasil memiliki title, url, dan description; atur extra_snippets=true dan Anda akan mendapatkan hingga lima kutipan tambahan per hasil, yang membantu saat Anda membangun konteks untuk sebuah model.

Brave membuat versi API dengan header Api-Version opsional dalam format YYYY-MM-DD. Abaikan saja dan Anda akan mendapatkan versi terbaru; sematkan itu setelah integrasi Anda dalam produksi agar perubahan besar di masa depan tidak datang tanpa diundang.

Langkah 5: Uji kunci di Apidog

Menempelkan kunci ke dalam satu baris perintah curl baik untuk percobaan pertama. Tapi itu bukan tempat yang baik untuk menyimpannya. Di Apidog Anda menyimpan kunci sekali sebagai variabel, merujuknya di mana saja, dan menjaga rahasia itu sendiri terpisah dari proyek bersama.

1. Buka manajemen lingkungan di kanan atas proyek Apidog Anda dan tambahkan lingkungan bernama Brave. Buat variabel bernama brave_api_key dan masukkan kunci sebenarnya di bidang nilai lokal, bukan nilai bersama. Nilai lokal tetap berada di mesin Anda dan tidak pernah disinkronkan ke rekan tim; referensi variabel menjelaskan model dua nilai, dan alur kerja lengkap untuk lingkungan dan variabel rahasia di Apidog mencakup tata letak dev, staging, dan prod jika Anda membutuhkan lebih dari satu.
2. Buat permintaan GET baru ke https://api.search.brave.com/res/v1/web/search. Di tab Headers, tambahkan X-Subscription-Token dengan nilai {{brave_api_key}}. Di Params, tambahkan q, count, dan freshness.
3. Klik Kirim. Panel respons akan menampilkan isi JSON, dan panel header akan menampilkan X-RateLimit-Remaining serta X-RateLimit-Reset, sehingga Anda dapat memantau kuota Anda tanpa mencetak apa pun.
4. Tambahkan pernyataan: kode status sama dengan 200, $.web.results ada dan memiliki setidaknya satu elemen, dan $.query.original cocok dengan kueri yang Anda kirim. Simpan permintaan tersebut ke dalam skenario pengujian. Kini, rotasi kunci atau perubahan di sisi Brave akan muncul sebagai kegagalan daripada agen yang rusak pada pukul 2 pagi.

Unduh Apidog untuk mengikuti; paket gratis mencakup empat pengguna dan termasuk lingkungan serta skenario pengujian.

Batas Laju dan Cara Brave Melaporkannya

Setiap respons membawa empat header, yang didokumentasikan dalam panduan pembatasan laju Brave:

• X-RateLimit-Limit: batasan yang terkait dengan paket Anda, misalnya 1, 15000.
• X-RateLimit-Policy: batasan yang sama dengan ukuran jendela dalam detik, misalnya 1;w=1, 15000;w=2592000 (jendela satu detik dan jendela 30 hari).
• X-RateLimit-Remaining: sisa dalam setiap jendela.
• X-RateLimit-Reset: detik hingga setiap jendela diatur ulang.

Dua detail penting untuk penganggaran. Pertama, panduan menyatakan bahwa hanya respons yang berhasil dan tanpa kesalahan yang dihitung terhadap kuota, jadi lonjakan 422 dari kesalahan ketik tidak akan memakan kredit. Kedua, angka per detik dalam header contoh tersebut (1 permintaan per detik) adalah ilustrasi dokumen, bukan 50 permintaan per detik yang diiklankan oleh paket Search. Baca header Anda sendiri daripada berasumsi.

Kesalahan Umum dan Apa yang Harus Dilakukan

Kegagalan autentikasi pada kunci baru. Panduan autentikasi Brave menyatakan setiap permintaan harus membawa X-Subscription-Token, dan nilai yang hilang atau tidak valid akan ditolak. Ini biasanya muncul sebagai HTTP 401 dengan kode kesalahan token-invalid, meskipun referensi API Brave tidak menjelaskan statusnya. Periksa tiga hal: nama header harus tepat (bukan Authorization), kunci disalin tanpa spasi kosong di akhir, dan paket aktif di akun. Jika Anda tidak yakin mengapa skema ini berbeda dari bearer auth, lihat kunci API vs token bearer.

422 Entitas Tidak Dapat Diproses. Parameter di luar jangkauan atau salah format: count di atas 20, offset di atas 9, nilai freshness yang tidak dikenal, atau q yang kosong. Isi mengikuti skema kesalahan Brave:

{
  "type": "ErrorResponse",
  "error": {
    "id": "<unique occurrence id>",
    "status": 422,
    "code": "<application error code>",
    "detail": "<what went wrong>",
    "meta": {}
  },
  "time": 0
}

Baca error.detail; ini akan menyebutkan nama fieldnya.

429 Terlalu Banyak Permintaan. Anda mencapai batas jendela per detik atau kehabisan kredit. Brave mendokumentasikan RATE_LIMITED dan QUOTA_LIMITED sebagai kode kesalahan, jadi periksa mana yang Anda dapatkan: menunggu sejumlah detik di X-RateLimit-Reset dan mencoba lagi dengan backoff (Brave menyarankan 1 detik, 2 detik, 4 detik) memperbaiki yang pertama, dan hanya mengisi ulang kredit atau menunggu reset bulanan yang memperbaiki yang kedua.

FAQ

Apakah Brave Search API gratis?

Sebagian. Setiap paket mendapatkan $5 dalam bentuk kredit setiap bulan, yang setara dengan sekitar 1.000 permintaan Pencarian. Di luar itu Anda membayar $5,00 per 1.000 permintaan. Tidak ada cara untuk mengaktifkan paket tanpa kartu kredit, bahkan jika Anda tidak pernah melebihi kredit.

Apakah saya memerlukan kunci terpisah untuk pencarian web dan endpoint Konteks LLM?

Referensi API Brave menjelaskan token sebagai yang dihasilkan "untuk produk", yang menunjukkan bahwa kunci terkait dengan langganan di mana kunci itu dibuat. Jika kunci yang berfungsi di /web/search gagal di /llm/context atau endpoint Answers, periksa paket mana yang menjadi milik kunci tersebut di dasbor sebelum berasumsi kunci tersebut rusak.

Bagaimana jika kunci API Brave saya bocor?

Cabut kunci tersebut di bagian Kunci API, buat penggantinya, dan perbarui variabel di Apidog agar setiap permintaan yang disimpan segera menggunakan nilai baru. Kemudian cari tahu bagaimana kunci itu bocor: menjalankan pemindai rahasia untuk kunci API yang bocor di seluruh repositori dan log CI Anda adalah cara tercepat untuk mengonfirmasi tidak ada hal lain yang terekspos.

Bisakah saya mencoba kueri tanpa menulis kode?

Ya. Dasbor mencakup halaman Playground untuk kueri ad-hoc, dan pembuat permintaan Apidog melakukan hal yang sama dengan manfaat tambahan bahwa permintaan disimpan dan dapat diuji setelahnya.

Langkah Selanjutnya

Anda memiliki akun, paket aktif, kunci bernama, dan permintaan yang mengembalikan hasil nyata dari tiga klien. Dari sini, Anda bisa menghubungkan kunci tersebut ke agen melalui server MCP, atau membangun skenario pengujian Apidog agar rotasi kunci dan kehabisan kuota dapat terdeteksi sebelum pengguna Anda menyadarinya. Keduanya dimulai dengan header X-Subscription-Token yang sama yang Anda atur hari ini.