| name | brave-search |
| description | Use when user asks to search the web, look something up online, find current/recent/latest information, or needs cited answers. Triggers on "search", "look up", "find out about", "what is the current/latest", image searches, news lookups. NOT for searching code/files—only for web/internet searches. |
Brave Search API
Overview
Search the web, images, and news using Brave's privacy-focused Search API. Also supports AI Grounding for cited answers via OpenAI SDK compatibility.
Prerequisites
API Key required. Get one at https://api-dashboard.search.brave.com
export BRAVE_API_KEY="your-api-key"
Free tier: 2,000 queries/month. Pro plans unlock Local POI search and AI Grounding.
When to Use
- Searching the web for current information
- Finding images on a topic
- Getting recent news articles
- AI-grounded answers with citations
- Autocomplete suggestions
- Location/POI searches (Pro plan)
High-Throughput Usage
Go wide, go fast. This API supports high concurrency—up to 50 requests/second. Don't hold back:
- Fire searches in parallel. Need to research 10 different topics? Launch 10 searches simultaneously. Use multiple Bash tool calls in a single message.
- Use subagents for heavy results. When expecting lots of context (many results, extra snippets, research mode), dispatch a subagent to run the search and synthesize findings. This preserves your main context window.
- Batch related queries. Searching for competitors, alternatives, or multiple aspects of a topic? Run them all at once.
digraph parallel_search {
rankdir=LR;
node [shape=box];
task [label="Research task"];
q1 [label="Query 1"];
q2 [label="Query 2"];
q3 [label="Query 3"];
subagent [label="Subagent\n(preserves context)"];
synthesize [label="Synthesized\nfindings"];
task -> q1;
task -> q2;
task -> q3;
q1 -> subagent [style=dashed];
q2 -> subagent [style=dashed];
q3 -> subagent [style=dashed];
subagent -> synthesize;
}
When to use subagents:
- Searching for many sources on a topic (launch search subagent, return summary)
- Deep research with AI Grounding (high token usage, let subagent handle)
- Comparing multiple options (run parallel searches, subagent synthesizes)
When to search directly:
- Quick single queries where you need the raw URLs/snippets
- Low result counts where context isn't a concern
Quick Reference
| Task | Command |
|---|
| Web search | brave-search web "query" |
| Image search | brave-search images "query" |
| News search | brave-search news "query" |
| AI answer | brave-search ai "question" |
| Suggestions | brave-search suggest "partial query" |
| Check key | brave-search check-key |
API Endpoints
| API | Endpoint | Plan |
|---|
| Web Search | /res/v1/web/search | Free |
| Image Search | /res/v1/images/search | Free |
| News Search | /res/v1/news/search | Free |
| Suggest | /res/v1/suggest/search | Free |
| AI Grounding | /res/v1/chat/completions | AI Grounding |
| Local POI | /res/v1/local/pois | Pro |
| Summarizer | /res/v1/summarizer/search | Pro |
Common Parameters
Web Search
brave-search web "python async tutorial" --count 10
brave-search web "latest news" --freshness pd
brave-search web "local restaurants" --country US --lang en
brave-search web "query" --safesearch strict
brave-search web "query" --extra-snippets
brave-search web "query" --filter web,news
Image Search
brave-search images "mountain sunset"
brave-search images "landscape" --safesearch strict --count 20
News Search
brave-search news "AI developments" --count 10
brave-search news "election results" --freshness pd
AI Grounding (Cited Answers)
brave-search ai "What is the tallest building in the world?"
brave-search ai "Compare React and Vue in 2024" --research
Workflow
digraph brave_search {
rankdir=TB;
node [shape=box];
need [label="What do you need?" shape=diamond];
web [label="Web Search\nbrave.py web"];
images [label="Image Search\nbrave.py images"];
news [label="News Search\nbrave.py news"];
ai [label="AI Answer\nbrave.py ai"];
results [label="Parse JSON results"];
cite [label="Include citations\nfor AI answers"];
need -> web [label="web pages"];
need -> images [label="images"];
need -> news [label="recent news"];
need -> ai [label="cited answer"];
web -> results;
images -> results;
news -> results;
ai -> cite;
}
Response Structure
Web Search Results
{
"web": {
"results": [
{
"title": "Page Title",
"url": "https://example.com",
"description": "Snippet from the page...",
"extra_snippets": ["Additional context..."]
}
]
},
"query": {
"original": "search query",
"altered": "modified query if spellchecked"
}
}
AI Grounding Response
Returns OpenAI-compatible format with inline citations:
The tallest building is the Burj Khalifa[1] at 828 meters...
[1] https://source-url.com
Common Options
| Option | Values | Description |
|---|
--count | 1-20 (web), 1-200 (images) | Number of results |
--country | US, GB, DE, FR, etc. | Search region |
--lang | en, de, fr, es, etc. | Search language |
--safesearch | off, moderate, strict | Adult content filter |
--freshness | pd, pw, pm, py | Time filter |
--json | flag | Output raw JSON |
Error Handling
| Error | Cause | Fix |
|---|
| 401 Unauthorized | Invalid/missing API key | Check BRAVE_API_KEY |
| 429 Rate Limited | Too many requests | Wait or upgrade plan |
| 422 Validation | Invalid parameters | Check parameter values |
Rate Limits
- Free: 1 req/sec, 2,000/month
- Pro: Higher limits, check dashboard
- Response headers show remaining quota:
X-RateLimit-Remaining
Common Mistakes
| Mistake | Fix |
|---|
| API key not set | export BRAVE_API_KEY="..." |
| Wrong endpoint for plan | Check subscription at dashboard |
| Too many results | Web max is 20, use offset for pagination |
| No AI grounding | Requires AI Grounding subscription |
