Web Search (Brave Search API)

Search the web using Brave's Search API. Returns web results with descriptions, optional extra snippets, and support for country/language targeting.

Note: This skill requires a Brave Search API key. For basic web search using the agent's built-in capability, see

web-search

. For AI-optimized results with relevance scores, see

web-search-tavily

When to Use This Skill

Use this skill when:

You need to find current information not in your training data
The user asks about recent events, news, or updates
You need localized search results for a specific country or language
You want a privacy-respecting search alternative
Research requires real-time web data
Keywords mentioned: search, look up, find online, current, latest, news

Do NOT use this skill when:

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:

bash

deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "your search query"

Example with freshness filter:

bash

deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "React 19 new features" --freshness pw

Script Usage

bash

deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts [options] "query"

Options

Option	Description	Default
`--results <n>`	Number of results to return (max 20)	5
`--freshness <range>`	Time filter: `pd` , `pw` , `pm` , or `py`	none
`--country <code>`	Country code for localized results (e.g., US, GB, DE)	none
`--lang <code>`	Search language (e.g., en, fr, de)	none
`--safesearch <level>`	Safe search: `off` , `moderate` , or `strict`	moderate
`--extra-snippets`	Include additional content snippets	false
`--offset <n>`	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)

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

bash

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

bash

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

bash

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

bash

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:

bash

export BRAVE_API_KEY="your-api-key-here"

Or run with the variable inline:

bash

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

Related Skills

web-search: Basic web search using the agent's built-in capability
web-search-tavily: AI-optimized search with relevance scores and answer summaries
research-workflow: For comprehensive research projects that use multiple searches with planning and synthesis

web-search-brave

NPX Install

Tags

SKILL.md Content

Web Search (Brave Search API)

When to Use This Skill

Prerequisites

Quick Start

Script Usage

Options

Search Parameters

Freshness Values

Country Codes

Safe Search Levels

Output Format

Human-Readable Output (default)

JSON Output (--json)

Result Fields

Examples

Example 1: Current Events Search

Example 2: Documentation Lookup

Example 3: Localized Search

Example 4: Filtered Search with JSON Output

Common Issues and Solutions

Issue: "BRAVE_API_KEY environment variable is not set"

Issue: "Invalid Brave Search API key"

Issue: "Brave Search API rate limit exceeded"

Issue: No results returned

Limitations

Related Skills