Information is already in your knowledge base and doesn't need verification
The user asks about historical facts that don't change
You're working with local files or code (use other tools)
A more specific skill exists for the task (e.g., documentation lookup)
You need AI-generated answer summaries (use
web-search-tavily
instead)
Prerequisites
Before using this skill, ensure:
BRAVE_API_KEY
environment variable is set with a valid API key
Deno
is installed (for running the search script)
Internet access
is available
Get a Brave Search API key at:
https://brave.com/search/api/
Quick Start
Run a simple search:
deno run --allow-env --allow-net
=
api.search.brave.com scripts/search.ts
"your search query"
Example with freshness filter:
deno run --allow-env --allow-net
=
api.search.brave.com scripts/search.ts
"React 19 new features"
--freshness
pw
Script Usage
deno run --allow-env --allow-net
=
api.search.brave.com scripts/search.ts
[
options
]
"query"
Options
Option
Description
Default
--results
Number of results to return (max 20)
5
--freshness
Time filter:
pd
,
pw
,
pm
, or
py
none
--country
Country code for localized results (e.g., US, GB, DE)
none
--lang
Search language (e.g., en, fr, de)
none
--safesearch
Safe search:
off
,
moderate
, or
strict
moderate
--extra-snippets
Include additional content snippets
false
--offset
Pagination offset
0
--json
Output as JSON (for programmatic use)
false
--help
Show help message
-
Search Parameters
Freshness Values
Filter results by recency:
pd
Past day (last 24 hours)
pw
Past week (last 7 days)
pm
Past month (last 30 days)
py
Past year (last 365 days)
Country Codes
Use standard 2-character country codes to get localized results:
US
(United States),
GB
(United Kingdom),
DE
(Germany),
FR
(France),
JP
(Japan), etc.
Safe Search Levels
off
No filtering
moderate
(default): Filters explicit content
strict
Strictest filtering
Output Format
Human-Readable Output (default)
Search: "React 19 new features"
Found 5 results in 189ms
1. React 19 Release Notes
https://react.dev/blog/2024/04/25/react-19
React 19 is now available on npm! This release includes...
Age: 2 months ago
2. What's New in React 19
https://example.com/react-19-features
A comprehensive overview of React 19's new features...
JSON Output (--json)
{
"query"
:
"React 19 new features"
,
"results"
:
[
{
"title"
:
"React 19 Release Notes"
,
"url"
:
"https://react.dev/blog/2024/04/25/react-19"
,
"description"
:
"React 19 is now available on npm..."
,
"age"
:
"2 months ago"
,
"language"
:
"en"
,
"family_friendly"
:
true
}
]
,
"response_time"
:
189
,
"total_results"
:
1250000
}
Result Fields
Field
Type
Description
title
string
Page title
url
string
Source URL
description
string
Relevant excerpt from the page
extra_snippets
string[]
Additional content snippets (only with --extra-snippets)
age
string
How old the result is (e.g., "2 hours ago")
language
string
Language of the result
family_friendly
boolean
Whether the result is family-friendly
Examples
Example 1: Current Events Search
Scenario
Find recent news about a technology topic
scripts/search.ts
"OpenAI GPT-5 announcement"
--freshness
pw
--results
10
Expected output
Recent web results about GPT-5 from the past week
Example 2: Documentation Lookup
Scenario
Find specific technical documentation
scripts/search.ts
"Deno deploy edge functions tutorial"
--results
10
--extra-snippets
Expected output
Comprehensive results with extra snippets from documentation and tutorial sites
Example 3: Localized Search
Scenario
Find results targeted to a specific country and language
scripts/search.ts
"aktuelle Nachrichten"
--country
DE
--lang
de
--freshness
pd
Expected output
German-language results from Germany from the past day
Example 4: Filtered Search with JSON Output
Scenario
Get structured results with strict safe search
scripts/search.ts
"machine learning tutorials"
--safesearch
strict --extra-snippets
--json
Expected output
JSON results with extra snippets, filtered for safe content
Common Issues and Solutions
Issue: "BRAVE_API_KEY environment variable is not set"
Symptoms
Script exits immediately with API key error
Solution
:
Get an API key from
https://brave.com/search/api/
Set the environment variable:
export
BRAVE_API_KEY
=
"your-api-key-here"
Or run with the variable inline:
BRAVE_API_KEY
=
"your-key"
deno run --allow-env --allow-net
=
api.search.brave.com scripts/search.ts
"query"
Issue: "Invalid Brave Search API key"
Symptoms
401 authentication error
Solution
:
Verify your API key is correct (no extra spaces)
Check if your API key has expired
Verify your Brave Search API subscription is active
Issue: "Brave Search API rate limit exceeded"
Symptoms
429 error response
Solution
:
Wait a moment and retry
Reduce request frequency
Consider upgrading your Brave Search API plan for higher limits
Issue: No results returned
Symptoms
Empty results array
Solution
:
Try broader search terms
Remove country or language filters that might be too restrictive
Remove or widen the freshness filter
Check if the topic exists online
Limitations
This skill has the following limitations:
Requires active internet connection
API rate limits apply based on your Brave Search API plan
Results depend on Brave's index coverage
Cannot access paywalled or login-required content
No built-in AI-generated answer summaries (use
web-search-tavily
for that)
Maximum 20 results per request
Extra snippets require a paid API plan