Brave Search API 是主要 agent 可以使用的 web retrieval 候選。Brave 官方 pricing 目前列 Search 方案每 1,000 requests USD 5，並每月自動套用 USD 5 free credits；如果只看標準 Web Search，方向上約等於每月 1,000 次查詢，但實際要以帳戶 plan、endpoint、搜尋類型和 dashboard read-back 為準。這是搜尋 credits，不是 LLM input／output tokens，也不是可以永久保存的網路資料集。
當日敲門工具：Web Search／LLM context retrieval（不是 chat model）
Brave 當日 Search plan 把 Web search、可供模型與 agent 使用的 LLM context、news／videos／images 等能力放在同一個搜尋方案；它沒有把一個可獨立選擇的免費 chat model token 池交給學生。主要 agent 的第一個入口仍應是最小的 Web Search：短 query、少量 results、只取必要欄位，再回到第一方來源核對；若帳戶另有 LLM context 或 Answers，必須把 plan、query cost、token cost 和資料條款分開 read-back。
因此本篇的「最好免費敲門」不是把 Brave Search 寫成聊天模型，而是用 Search plan 的免費 credits 做一次可審計 retrieval canary。只查公開官方文件、設定 result_filter=web、count 不超過必要數量，保存 URL、title、snippet 的短期 evidence，並在任務結束刪除 raw response；結果不直接成為 system instruction、永久 RAG corpus 或模型訓練資料。
這個方案的主要風險是免費不代表零付款風險。Brave 官方說訂閱免費方案仍需要信用卡作反濫用驗證，使用完 included credits 後，額外使用會以 pay-as-you-go 計費，dashboard 可設定 spending limits。學生 agent 因此只能在本人帳戶、本人 payment consent、明確 spending limit、fresh credit read-back 和人工停止都完成後，做極短的搜尋 canary。
本篇不代註冊、不輸入信用卡、不取得或分享 Brave subscription token、不把搜尋結果長期保存、不用多帳戶或輪換 key／IP 規避 rate limit，也不把 Search Results 拿去訓練、評估、benchmark、fine-tune 或改善其他 AI model。主要 agent 的批准範圍是「即時查詢、暫存於單一任務、回傳可核對的 URL 與摘要」，不是建立自己的搜尋索引。
本系列只整理合法公開的免費 API 方案。若要先看主要 agent 的憑證、資料與人工停止原則，可延伸閱讀 AI agent 使用 FAQ；Brave Search API 的結果也必須遵守第三方頁面的版權、robots、條款和資料使用限制。
每月 USD 5 credits 的精確範圍
Brave pricing 頁目前把 Search 方案列為每 1,000 requests USD 5，包含 web search、news、images、videos 和 LLM context 等搜尋能力，並列 Search capacity 50 requests per second。Search 的 USD 5 free credits 每月自動套用，所以單純以標準 Search pricing 粗略換算，約是 1,000 requests；粗略換算不是 provider 的固定 query quota，不能用來覆蓋其他 plan 或其他 endpoint。
Answers 是另一種方案：官方 pricing 目前列每 1,000 queries USD 4，另按 input 和 output tokens 各每 1,000,000 tokens USD 5 計算，也有每月 USD 5 free credits。這表示 Answers 的免費使用不能簡化成「1,250 次回答」；每次回答的搜尋數與 tokens 會影響 credits 消耗。本文主要示範 Web Search，不把 Answers 的 LLM cost 混進 Search 的估算。
Spellcheck 和 Autosuggest 也各有獨立的 pricing、credits 和 capacity。API plan、subscription、key 和 monthly balance 要分開記錄；建立多支 key 不會增加免費 credits。學生如果只是要找官方文件，先使用 Search plan 的單一 endpoint；不要為了同一個任務同時開 Search、Answers、Place、Spellcheck 和 Autosuggest，造成不清楚的付款池。
Brave 舊版介紹文章曾以每月 2,000 queries 和每秒 1 query 描述免費方案，當日 pricing／dashboard 現在則以每月 USD 5 credits、Search 50 requests per second 顯示；這是來源版本變化，不應自行挑一個數字當永久承諾。本篇採用當日較新的 pricing 和 rate-limit 文件，但 live 使用前仍要讀回帳戶實際 plan header、credits、capacity 和 payment status。
信用卡與超額付費的硬性閘門
Brave 的免費方案需要 payment details。官方 FAQ 說信用卡是反詐騙與身份確認用途，並不代表免費方案沒有付款風險；API help 文件進一步說，信用卡也用於 included monthly credits 之外的使用。這一點和「不用信用卡的免費 API」完全不同，所以本篇不把 Brave Search API 排進零付款風險清單。
如果本人決定建立帳戶，先閱讀 subscription plan、spending limit、pay-as-you-go、billing cycle、credit reset 和 payment method，再由本人手動確認。主要 agent 不得代替帳戶持有人勾選付款同意、調高 limit、開啟 auto-charge、補卡或 upgrade。若 dashboard 沒有清楚顯示 limit 會如何阻止超額，保守做法是不上線，維持本地 stub。
function assertBraveFreeSearchState(state, now = Date.now()) {
if (state.plan !== 'search') {
throw new Error('Brave Search plan is not verified');
}
if (!Number.isFinite(state.freeCreditsUsd) ||
state.freeCreditsUsd <= state.reserveUsd) {
throw new Error('Brave free-credit reserve is too low');
}
if (state.paygEnabled !== false || state.autoChargeEnabled === true) {
throw new Error('Brave paid path is not approved');
}
if (state.spendingLimitUsd !== 0) {
throw new Error('Brave spending limit is not the local zero-spend policy');
}
if (state.checkedAt + state.maxReadbackAgeMs < now) {
throw new Error('Brave billing read-back is stale');
}
}這段是主要 agent 的本地政策，不是 Brave dashboard 的固定 schema。官方文件只保證可以設定 spending limits，不代表每個帳戶、plan 或 UI 都會以相同方式暴露 paygEnabled 或 autoChargeEnabled。帳戶持有人需要把實際 dashboard 欄位映射到本地 policy；任何欄位讀不到，就視為不明，不是當成 false。
若帳戶必須保留信用卡才能使用免費 credits，學生要先評估家庭、學校或管理者是否同意可能的 overage liability。即使本地程式設 spendingLimitUsd 為零，也要保留 provider dashboard 的確認時間、payment state、credit balance 和人工批准記錄。不要把一段程式碼當成銀行或 provider 的付款保證。
API key、endpoint 與 Search request
Brave 官方 authentication 文件目前要求每個 API request 在 X-Subscription-Token header 傳 subscription token。一般 web search endpoint 是 https://api.search.brave.com/res/v1/web/search，query 至少包含 q，也可以依文件加入 count、country、search_lang 和其他參數。token 是秘密，只能放 server-side environment 或受控 secret store，不放瀏覽器、公開 repository、issue、URL、log 或 agent prompt。
官方 quickstart 把 API Dashboard、authentication guide、API reference、rate limiting 和 versioning 分開。學生不要只複製一段 curl 就宣稱整合完成；還要確認自己訂閱的是 Search plan、key 對應該 plan、endpoint 是同一版本、account region／billing 狀態可讀回，並把 source query 做 PII 和 prompt-injection 分類。
async function braveWebSearch(query, state) {
assertBraveFreeSearchState(state);
const token = process.env.BRAVE_SEARCH_API_KEY;
if (!token) throw new Error('Brave Search API token is missing');
const text = String(query).trim();
if (text.length === 0 || text.length > 400) {
throw new Error('Brave query is outside the local bound');
}
const url = new URL('https://api.search.brave.com/res/v1/web/search');
url.searchParams.set('q', text);
url.searchParams.set('count', '10');
url.searchParams.set('search_lang', 'zh-hant');
url.searchParams.set('result_filter', 'web');
const response = await fetch(url, {
headers: {
Accept: 'application/json',
'X-Subscription-Token': token
}
});
const data = await response.json().catch(() => ({}));
if (!response.ok) {
throw Object.assign(new Error(`Brave Search HTTP ${response.status}`), {
status: response.status,
headers: Object.fromEntries(response.headers),
data
});
}
return { data, headers: Object.fromEntries(response.headers) };
}這段示意沒有真實 token，也沒有執行 live query。正式 adapter 要加 AbortController、總 timeout、來源 query policy、response schema validation、maximum results、safe search、allowed domains 和人工核對。query 裡若含有 API key、cookie、病歷、學號、客戶姓名、內網主機或秘密，就在本地拒絕，不把它送給搜尋 provider。
Rate-limit headers 比猜測更重要
Brave rate limiting 文件目前說限制以每秒 sliding window 計算，並在 response headers 提供 X-RateLimit-Limit、X-RateLimit-Policy、X-RateLimit-Remaining 和 X-RateLimit-Reset。範例同時表示每秒與每月兩個 window；主要 agent 必須解析實際 header，而不是硬編一個 1 qps、50 qps 或 2,000 queries 的數字。
function readBraveRateLimit(headers) {
const get = (name) => String(headers.get?.(name) ?? headers[name] ?? '');
const remaining = get('X-RateLimit-Remaining')
.split(',').map(value => Number(value.trim()));
const reset = get('X-RateLimit-Reset')
.split(',').map(value => Number(value.trim()));
return {
remaining,
resetSeconds: reset,
exhausted: remaining.some(value => Number.isFinite(value) && value <= 0)
};
}
function shouldRetryBrave(status, headers, attempt) {
if (status !== 429 || attempt >= 3) return false;
const limit = readBraveRateLimit(headers);
return !limit.exhausted || limit.resetSeconds.some(value => value > 0);
}官方文件指出成功 responses 才會計入 quota、失敗 requests 不計入，但這不批准無限失敗重試。429 仍然消耗時間、造成壓力並可能讓下游重複執行；重試要讀 reset、限制最大 attempts、固定 jitter 和總 timeout。headers 缺失、格式不明或 plan window 與預期不同時，停止並人工讀回 dashboard。
Web search 的 plan capacity 和 Answers 的 2 requests per second 不同，Place Search 也可能另有 billing。不要把搜尋 endpoint 的 header 直接套到 Answers、News、Images 或 Place。每一個 endpoint 都應保存 plan、operation、request cost、rate window、result count 和 source URL；如果不需要某個 endpoint，就不要訂閱或呼叫它。
Search Results 只能短暫使用
Brave Search API Terms 目前禁止把 Search Results 儲存、cache 或建立資料庫，除非是 Customer Application 運作所需的 transient storage；也禁止重新分發、轉售、公開提供或把 results 拿去 create、evaluate、train、re-train、fine-tune、benchmark 或 improve AI models。這對主要 agent 是硬邊界：搜尋結果可以在單一任務中即時交給已批准的下游流程，但不能建立長期 RAG corpus。
因此 agent 的回應可以保留當次必要的 URL、標題、時間和人工引用標記，但不應把完整 snippets、raw JSON、排名、網頁文字或 result cache 寫進永久資料庫。若產品需要長期保存、訓練或重複提供 Search Results，必須選擇明確授權 storage rights 的 plan，並另做法律、版權、資料治理與產品核准；免費 credits 本身不授予這些權利。
Search API 不授予第三方頁面內容的版權。Brave 官方提醒，客戶存取 API 顯示的 URL 時，仍要遵守頁面出版者的 copyright terms。搜尋結果是 discovery 和 citation starting point，不是把整篇文章複製到自己的網站或模型裡的授權。遇到 paywall、noindex、robots、登入、個資或明確禁止自動抓取的頁面，agent 應停止深入存取。
function makeTransientBraveCitation(result, taskId) {
const web = Array.isArray(result?.web?.results) ? result.web.results : [];
return web.slice(0, 5).map(item => ({
taskId: String(taskId),
title: String(item.title ?? '').slice(0, 300),
url: String(item.url ?? ''),
age: item.age ? String(item.age) : null,
sourceCapturedAt: new Date().toISOString()
}));
}
function discardBraveRawResults(raw, transientCitations) {
if (!Array.isArray(transientCitations)) {
throw new Error('Transient citation contract is missing');
}
return { citations: transientCitations, rawResultsDeleted: Boolean(raw) };
}這段示意只保留當次任務最小的 title、URL、age 和時間，不代表所有使用情境都已取得儲存授權。若同一個任務的人工審查需要短暫 raw response，就設定明確 TTL、記錄用途和刪除事件；任務結束刪除 raw JSON、snippets、local cache 和暫存檔。不要把「transient」解釋成可以無限期放在 log 或備份。
Query privacy 與美國資料處理
Brave Search API privacy notice 目前說服務由美國 Brave Software 提供，建立帳戶要提供 payment、postal address 和 billing details；Stripe 處理 payment information。該 notice 也說經由 API 帳戶送出的 search queries 最多保留 90 天，用於 billing、troubleshooting 和法律義務。這和 Brave Search browser 的一般隱私宣稱不能混為一談，API 客戶要閱讀自己的 API privacy notice。
如果 product 讓 end user 直接輸入問題，Brave privacy notice 說 API customer 對適用資料保護法、自己的 privacy notice 和 end-user 告知負責。主要 agent 應先在本地做 query minimization：刪除姓名、電話、地址、email、學號、病例、客戶代號和秘密，只留下完成搜尋必要的 terms。不要把整段聊天歷史作為 query。
搜尋 query 本身也可能是敏感資料。例如「某校某名學生的醫療紀錄」即使只送一次，也可能產生高風險 metadata。Agent 要把 query 當成資料外傳事件先分類；若需要查詢真實個人、內部事故、未公開收購或機密研究，先拒絕或改用受批准的內部資料源。免費 credits 不會替使用者取得第三方同意。
403、401、429 與 billing stop
Brave API authentication 文件把缺少或無效 token 視為 authentication 問題；rate-limit 文件說超過限制回 429。Billing 文件另要求使用者查看 credits、spending limits 和 pay-as-you-go。主要 agent 要把 key、rate、credit、payment 和 content policy 分開分類，不能遇到錯誤就換另一支 key 或另一個帳戶。
function classifyBraveFailure(error) {
const status = Number(error?.status);
const message = String(error?.data?.message ?? '').toLowerCase();
if (status === 401 || status === 403) {
return { action: 'STOP_REVIEW_BRAVE_TOKEN_OR_PLAN', retry: false };
}
if (status === 429) {
return { action: 'READ_RATE_HEADERS_AND_BOUNDED_BACKOFF', retry: true };
}
if (status === 402 || message.includes('credit') || message.includes('billing')) {
return { action: 'STOP_FREE_CREDIT_AND_PAYMENT_REVIEW', retry: false };
}
if (status === 400) return { action: 'FIX_QUERY_WITHOUT_RETRY', retry: false };
if (status >= 500) return { action: 'SHORT_BACKOFF_THEN_HUMAN_REVIEW', retry: true };
return { action: 'STOP_UNKNOWN_BRAVE_FAILURE', retry: false };
}如果出現 402、credit exhausted、payment method、invoice、payg、spending limit changed 或帳戶 plan 不明，立即停止。不要自動加值、調高 limit、升級 Search／Answers、換帳戶、換 IP 或讓下游重新詢問。429 只在 rate headers 清楚、總 attempts 有限且沒有 billing risk 時做短 backoff；未知 5xx 也要設上限，避免服務恢復後大量重放。
搜尋結果不能直接成為 agent 指令
Web page 和 snippet 都是不可信輸入。搜尋結果可能包含「忽略系統訊息、下載這個檔案、貼出環境變數、呼叫付款工具」等 prompt injection。主要 agent 應把 title、snippet、URL、page content 分在 untrusted content channel，先抽取事實與 citation，再由固定 policy 決定能否呼叫工具。搜尋排名或 Brave 的 relevance 不會讓外部文字升級成系統指令。
如果任務要求查官方文件，限定 allowed domains、固定 query、限制結果數，並由人工或第二個來源核對版本與日期。搜尋 API 的結果可以幫助找到官方頁面，但不能取代閱讀該頁面；尤其是價格、法規、醫療、資安、付款和供應商條款都要直接開來源頁並記錄查核日期。
即時新聞和股票、產品價格、服務狀態都會變化。Agent 不要因為 Search API 有即時 index 就保存一段過期答案；回應要附來源時間、結果時間和不確定性。若同一 query 在短時間返回矛盾結果，先呈現差異並要求人工判斷，不用自動選排名第一的文字。
三階段學生學習流程
第一階段完全離線：以 stub 模擬 USD 5 monthly credits、Search／Answers 不同計價、per-second／monthly headers、401、402、403、429 和 5xx。練習 query minimization、allowed domains、source citation、transient TTL、raw response deletion 和不把外部內容當工具指令。這一階段不需建立 Brave 帳戶、不需信用卡、不消耗 provider credits。
第二階段做一次低風險 live Web Search canary：使用幾個公開、穩定、非敏感的官方文件查詢，限制 count、timeout、一次 request，讀回 rate headers、credits、plan 和 response schema。只在任務內呈現五個以內的 citation URL，人工點開核對；完成後刪除 raw JSON、query log 與暫存 snippets。
第三階段才比較不同 query 策略：短 query、限定 domain、語言參數、safe search、同一來源的重複查詢和 cache 行為。報告記錄 query hash、request cost、result count、rate header 和人工核對結果，不保存全文或建立資料庫。credits 接近 reserve 時提前停止，不等到 payment error 才處理。
學生期末成果可以交付 retrieval quality table、citation correctness、query minimization、錯誤分類、usage read-back 和刪除證據，不交付 API token、信用卡、帳戶畫面、完整 snippets、第三方全文或私密 query。這樣學到的是合規的 web-grounded agent adapter，而不是用免費額度大量複製網路內容。
本篇的學生 agent 決策
Brave Search API 可以列入「每月 USD 5 免費 web retrieval credits」候選：官方 pricing 目前有 Search、Answers、Spellcheck 和 Autosuggest 的區分，Search 方案約以每 1,000 requests USD 5 計價，每月自動套用 USD 5 credits。它不是免費 LLM token，也不是可永久保存的搜尋資料庫；主要 agent 只能把它當成短暫、可引用、可停止的外部檢索工具。
但它不屬於「不用付款資料、超額絕對不扣款」的安全免費層。信用卡是免費訂閱前置條件，超過 credits 可能 pay-as-you-go，搜尋結果保存和 AI training 也有 Terms restrictions。因此本人若沒有明確同意 payment risk、spending limit、query privacy、90 天 query retention、第三方版權和不可保存結果，就不應建立帳戶或把它接進主要 agent。
若本人完成帳戶 read-back，建議只允許一個 Search adapter、一個 server-side token、一個小額度 reserve 和一個短任務 scope。每次請求先估算、再查 headers、再送出；回應只短暫保留 citation，遇到 billing、rate、content policy 或 provider terms 不明就停止。免費 credits 不應成為無人值守的背景搜尋。
每次搜尋都要有任務邊界和完成條件。先決定是找官方文件、比較公開產品、查詢日期，還是只做 discovery；不同目的需要不同 query、domain allowlist 和人工核對。結果數不宜為了看起來完整而盲目拉高，因為更多 snippets 會增加處理、引用和資料清理負擔，也可能把不必要的第三方內容帶進主要 agent。
citation read-back 至少要確認 URL 可以開啟、標題與內容相符、來源日期沒有被誤讀、頁面不是搜尋結果自己的摘要，以及引用文字沒有超過必要範圍。若來源只剩 snippet、連結失效、頁面需要登入或結果互相矛盾，回應要標成待核對，不用自動補全文或改寫成確定事實。
免費 credits 和搜尋結果的授權是兩條不同的軌道。即使帳戶尚有 USD 5，也不代表可以把結果放入訓練集；即使 Terms 允許 Customer Application 在任務中使用，也不代表可以把第三方頁面全文複製到自己的知識庫。主要 agent 的 ledger 要同時記錄 credit、rate、query purpose、source URL、citation status 和 deletion status。
若使用 Answers，還要把 provider 產生的回答和主要 agent 自己的 LLM 分開標記。Answers 有自己的搜尋費用、input token、output token、速率和 grounding 行為，不能把它的 token 當成免費主模型 token，也不能把一段 provider answer 當成經過人工查核的 final answer。需要可控推理時，較穩妥的做法是使用 Search 的來源與 context，再交給另行批准的模型。
如果未來改用 Tavily、Firecrawl、Bing 或其他 web provider，保留同一份本地 contract：query minimization、domain allowlist、短暫結果、citation read-back、rate headers、billing stop 和第三方版權檢查。不能把 Brave 的 USD 5、key、Search Results 權利或 90 天 query retention 直接假設搬到另一家服務；換 provider 前要重新查官方 pricing、terms、privacy、endpoint 和資料保存規則。
Brave Search 結果也不能替代官方來源核對。主要 agent 應以搜尋找到來源，再直接讀取允許的第一方頁面，保留來源 URL、發佈日期、查核日期和內容界線。不能把 Search snippet 當作完整法律條款、價格承諾、醫療建議或產品規格；不能把第一名結果當成唯一真相。
如果任務需要持久化知識庫、訓練資料、embedding corpus 或大規模網頁快照，Brave Search API 的免費 Search plan 不是適合的授權。應改做明確授權的資料來源研究，或選擇允許 storage／training rights 的合約 plan，再由法律與資安審查。不要用 transient storage 的例外包裝成永久 archive。
對課堂 agent 而言，最實用的設計是「搜尋一次、引用一次、刪除一次」。任務建立時先產生 query hash 和 budget reservation；回應時只把必要的 URL 交給人工 reviewer；任務完成後刪掉 raw response、snippets 和含 query 的 debug log。若需要重現，保存的是 provider 文件版本、測試條件和人工建立的 synthetic query，不是整批 Search Results。
每週或每個課程週期可以交付一張去識別化 usage report：plan、successful requests、估算 credits、rate-limit header、429 次數、citation 通過率、raw deletion 狀態和是否觸發人工 stop。報表不應包含 private query、payment details、完整 snippets 或 token。當 report 顯示 credit 消耗與 dashboard 不一致時，先停用 adapter，重新核對 endpoint、plan、免費 credits 和計價單位。
Brave 的 Terms、Privacy、pricing 和 API docs 可能在不同日期更新，尤其是免費 credits、Search capacity、Answers、storage rights 和 query retention。每次恢復 live 使用前都要記錄查核日期與文件版本；如果新條款縮小可用範圍，就把候選降級為本地 stub。文章的完成只表示官方證據與本機結構通過，不表示帳戶未來一定維持相同額度。
若 provider 回傳的 result 包含疑似個資、惡意下載連結或未預期的完整段落，agent 不要為了產生較好的答案而繼續擴大抓取。先停止、保留最小的錯誤分類和來源 URL，交由人工判斷是否需要另找公開且合適的第一方來源。這條線同時保護免費 credits、使用者隱私、第三方版權與主要 agent 的工具安全。
任何沒有明確 citation、授權或 budget evidence 的搜尋任務，都只做到本地規劃，不送出 API request。
這是學生 agent 的最小安全單位：來源可回讀、額度可核對、結果可刪除、付款可停止。
缺一項，就停在本地，不把「有免費 credits」誤報成已批准的燃料。
這個安全停止結果本身就是驗收證據。
安全通過。
截至 2026-08-25，本篇完成官方文件查核與本機草稿驗收，沒有進行 Brave 註冊、信用卡輸入、建立 subscription、建立 API key、live search、Answers、Place Search、付款、spending limit read-back 或外部 query。工作區沒有授權 Brave 帳戶，因此不代收、不建立、不分享 token、key、信用卡資料或私密搜尋內容。
Brave Search API 官方查核入口
- Brave Search API pricing、Search／Answers plans、free monthly credits 與 payment FAQ
- API Dashboard pricing：每月 USD 5 credits、各 endpoint 價格與 capacity
- Quickstart：API Dashboard、API reference 與 versioning
- Authentication：X-Subscription-Token 與 API key 安全
- Web Search API reference：endpoint 與 request parameters
- Rate limiting：sliding window、429 與 X-RateLimit headers
- Help and feedback：credit card、monthly credits、pay-as-you-go 與資料權利提醒
- Privacy notice：payment details、query retention 最多 90 天與 API customer responsibility
- Search API Terms：結果保存、AI training、rate-limit bypass 與版權限制
- Answers／grounding：搜尋與 input／output token 的分開計價
- Brave 官方方案歷史說明：免費計畫變更與舊版額度背景
下一篇會重新查找另一個官方免費 API 候選；Brave Search API 的 USD 5 monthly credits 不會被延伸成免費 LLM token，也不會因為文章完成就自動註冊、輸入信用卡、付款、保存搜尋結果或傳送私密 query。
分享此文：
KEEP READING
接著讀什麼？
從同一主題繼續閱讀，或回到 YOLO LAB 的完整文章索引，找到下一個值得投入時間的問題。
發表迴響