Web Search (Brave Search API)

web-search

web-search-tavily

When to Use This Skill

• 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

• 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

• BRAVE_API_KEY environment variable is set with a valid API key
• Deno is installed (for running the search script)
• Internet access is available

Quick Start

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

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

--results <n>

--freshness <range>

pd

pw

pm

py

--country <code>

--lang <code>

--safesearch <level>

off

moderate

strict

--extra-snippets

--offset <n>

--json

--help

Search Parameters

Freshness Values

• 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

• 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

title

url

description

extra_snippets

age

language

family_friendly

Examples

Example 1: Current Events Search

scripts/search.ts "OpenAI GPT-5 announcement" --freshness pw --results 10

Example 2: Documentation Lookup

scripts/search.ts "Deno deploy edge functions tutorial" --results 10 --extra-snippets

Example 3: Localized Search

scripts/search.ts "aktuelle Nachrichten" --country DE --lang de --freshness pd

Example 4: Filtered Search with JSON Output

scripts/search.ts "machine learning tutorials" --safesearch strict --extra-snippets --json

Common Issues and Solutions

Issue: "BRAVE_API_KEY environment variable is not set"

1. Get an API key from https://brave.com/search/api/
2. Set the environment variable:
   bash

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

3. 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"

1. Verify your API key is correct (no extra spaces)
2. Check if your API key has expired
3. Verify your Brave Search API subscription is active

Issue: "Brave Search API rate limit exceeded"

1. Wait a moment and retry
2. Reduce request frequency
3. Consider upgrading your Brave Search API plan for higher limits

Issue: No results returned

1. Try broader search terms
2. Remove country or language filters that might be too restrictive
3. Remove or widen the freshness filter
4. Check if the topic exists online

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