Skip to content
Brave Web Search

Brave Web SearchSkill

by Brave
Released
4 views
MIT
Repository Docs
markdown Development

Summary

Brave's official skill for the Brave Search API — ranked web results with snippets and thumbnails, freshness and SafeSearch filters, search operators, pagination, and Goggles for custom ranking.

Features

  • Ranked web results with snippets, URLs and thumbnails
  • Freshness filters for the past day, week, month or year
  • Goggles: custom re-ranking to bias results towards trusted sources
  • Documented response schema with a full JSON example for reliable parsing
  • Search operators, result filters, pagination and SafeSearch levels
  • Rich-data callback flow for structured verticals such as weather

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: web-search
description: USE FOR web search. Returns ranked results with snippets, URLs, thumbnails. Supports freshness filters, SafeSearch, Goggles for custom ranking, pagination. Primary search endpoint.
---

# Web Search

> **Requires API Key**: Get one at https://api.search.brave.com
>
> **Plan**: Included in the **Search** plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

## Quick Start (cURL)

### Basic Search
```bash
curl -s "https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"
```

### With Parameters
```bash
curl -s "https://api.search.brave.com/res/v1/web/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming tutorials" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "safesearch=moderate" \
  --data-urlencode "freshness=pm"
```

## Endpoint

```http
GET https://api.search.brave.com/res/v1/web/search
POST https://api.search.brave.com/res/v1/web/search
```

**Note**: Both GET and POST methods are supported. POST is useful for long queries or complex Goggles.

**Authentication**: `X-Subscription-Token: <API_KEY>` header

**Optional Headers**:
- `Accept-Encoding: gzip` — Enable gzip compression

## When to Use Web Search

| Feature | Web Search (this) | LLM Context (`llm-context`) | Answers (`answers`) |
|--|--|--|--|
| Output | Structured results (links, snippets, metadata) | Pre-extracted page content for LLMs | End-to-end AI answers with citations |
| Result types | Web, news, videos, discussions, FAQ, infobox, locations, rich | Extracted text chunks, tables, code | Synthesized answer + source list |
| Unique features | Goggles, structured data (`schemas`), rich callbacks | Token budget control, threshold modes | Multi-iteration search, streaming, OpenAI SDK compatible |
| Speed | Fast (~0.5-1s) | Fast (<1s) | Slower (~30-180s) |
| Best for | Search UIs, data extraction, custom ranking | RAG pipelines, AI agents, grounding | Chat interfaces, thorough research |

## Parameters

| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
| `ui_lang` | string | No | `en-US` | UI language (e.g., "en-US") |
| `count` | int | No | `20` | Max results per page (1-20) |
| `offset` | int | No | `0` | Page offset for pagination (0-9) |
| `safesearch` | string | No | `moderate` | Adult content filter (`off`/`moderate`/`strict`) |
| `freshness` | string | No | - | Time filter (`pd`/`pw`/`pm`/`py` or date range) |
| `text_decorations` | bool | No | `true` | Include highlight markers |
| `spellcheck` | bool | No | `true` | Auto-correct query |
| `result_filter` | string | No | - | Filter result types (comma-separated) |
| `goggles` | string | No | - | Custom ranking filter (URL or inline) |
| `extra_snippets` | bool | No | - | Get up to 5 extra snippets per result |
| `operators` | bool | No | `true` | Apply search operators |
| `units` | string | No | - | Measurement units (`metric`/`imperial`) |
| `enable_rich_callback` | bool | No | `false` | Enable rich 3rd party data callback |
| `include_fetch_metadata` | bool | No | `false` | Include `fetched_content_timestamp` on results |

### Freshness Values

| Value | Description |
|--|--|
| `pd` | Past day (24 hours) |
| `pw` | Past week (7 days) |
| `pm` | Past month (31 days) |
| `py` | Past year (365 days) |
| `YYYY-MM-DDtoYYYY-MM-DD` | Custom date range |

### Result Filter Values

Filter types: `discussions`, `faq`, `infobox`, `news`, `query`, `videos`, `web`, `locations`

```bash
# Only web and video results
curl "...&result_filter=web,videos"
```

### Location Headers (Optional)

For location-aware results, add these headers. **Lat/Long is sufficient** when coordinates are known — the other headers are only needed as a fallback when coordinates are unavailable.

| Header | Type | Description |
|--|--|--|
| `X-Loc-Lat` | float | User latitude (-90.0 to 90.0) |
| `X-Loc-Long` | float | User longitude (-180.0 to 180.0) |
| `X-Loc-Timezone` | string | IANA timezone (e.g., "America/San_Francisco") |
| `X-Loc-City` | string | City name |
| `X-Loc-State` | string | State/region code (ISO 3166-2) |
| `X-Loc-State-Name` | string | State/region full name (e.g., "California") |
| `X-Loc-Country` | string | 2-letter country code |
| `X-Loc-Postal-Code` | string | Postal code (e.g., "94105") |

> **Priority**: `X-Loc-Lat` + `X-Loc-Long` take precedence. When provided, downstream services resolve the location directly from coordinates and the text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers **only** when you don't have coordinates. Sending both won't break anything — lat/long simply wins.

## Response Format

### Response Fields

| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"search"` |
| `query.original` | string | The original search query |
| `query.altered` | string? | Spellcheck-corrected query (if changed) |
| `query.cleaned` | string? | Cleaned/normalized query |
| `query.spellcheck_off` | bool? | Whether spellcheck was disabled |
| `query.more_results_available` | bool | Whether more pages exist |
| `query.show_strict_warning` | bool? | True if strict safesearch blocked adult results |
| `query.search_operators` | object? | Applied search operators (`applied`, `cleaned_query`, `sites`) |
| `web.type` | string | Always `"search"` |
| `web.results[].title` | string | Page title |
| `web.results[].url` | string | Page URL |
| `web.results[].description` | string? | Snippet/description text |
| `web.results[].age` | string? | Human-readable age (e.g., "2 days ago") |
| `web.results[].language` | string? | Content language code |
| `web.results[].meta_url` | object | URL components (`scheme`, `netloc`, `hostname`, `path`) |
| `web.results[].thumbnail` | object? | Thumbnail (`src`, `original`) |
| `web.results[].thumbnail.original` | string? | Original full-size image URL |
| `web.results[].thumbnail.logo` | bool? | Whether the thumbnail is a logo |
| `web.results[].profile` | object? | Publisher identity (`name`, `url`, `long_name`, `img`) |
| `web.results[].page_age` | string? | ISO datetime of publication (e.g., `"2025-04-12T14:22:41"`) |
| `web.results[].extra_snippets` | list[str]? | Up to 5 additional excerpts |
| `web.results[].deep_results` | object? | Additional links (`buttons`, `links`) from the page |
| `web.results[].schemas` | list? | Raw schema.org structured data |
| `web.results[].product` | object? | Product info and reviews |
| `web.results[].recipe` | object? | Recipe details (ingredients, time, ratings) |
| `web.results[].article` | object? | Article metadata (author, publisher, date) |
| `web.results[].book` | object? | Book info (author, ISBN, rating) |
| `web.results[].software` | object? | Software product info |
| `web.results[].rating` | object? | Aggregate ratings |
| `web.results[].faq` | object? | FAQ found on the page |
| `web.results[].movie` | object? | Movie info (directors, actors, genre) |
| `web.results[].video` | object? | Video metadata (duration, views, creator) |
| `web.results[].location` | object? | Location/restaurant details |
| `web.results[].qa` | object? | Question/answer info |
| `web.results[].creative_work` | object? | Creative work data |
| `web.results[].music_recording` | object? | Music/song data |
| `web.results[].organization` | object? | Organization info |
| `web.results[].review` | object? | Review data |
| `web.results[].content_type` | string? | Content type classification |
| `web.results[].fetched_content_timestamp` | int? | Fetch timestamp (with `include_fetch_metadata=true`) |
| `web.mutated_by_goggles` | bool | Whether results were re-ranked by Goggles |
| `web.family_friendly` | bool | Whether results are family-friendly |
| `mixed` | object? | Preferred display order (see Mixed Response below) |
| `discussions.results[]` | array? | Forum discussion clusters |
| `discussions.results[].data.forum_name` | string? | Forum/community name |
| `discussions.results[].data.num_answers` | int? | Number of answers/replies |
| `discussions.results[].data.question` | string? | Discussion question |
| `discussions.results[].data.top_comment` | string? | Top-voted comment excerpt |
| `faq.results[]` | array? | FAQ entries |
| `news.results[]` | array? | News articles |
| `videos.results[]` | array? | Video results |
| `infobox.results[]` | array? | Knowledge graph entries |
| `locations.results[]` | array? | Local POI results |
| `rich.hint.vertical` | string? | Rich result type |
| `rich.hint.callback_key` | string? | Callback key for rich data |

### JSON Example

```json
{
  "type": "search",
  "query": {
    "original": "python frameworks",
    "altered": "python web frameworks",
    "spellcheck_off": false,
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Top Python Web Frameworks",
        "url": "https://example.com/python-frameworks",
        "description": "A comprehensive guide to Python web frameworks...",
        "age": "2 days ago",
        "language": "en",
        "meta_url": {
          "scheme": "https",
          "netloc": "example.com",
          "hostname": "example.com",
          "path": "/python-frameworks"
        },
        "thumbnail": {
          "src": "https://...",
          "original": "https://original-image-url.com/img.jpg"
        },
        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
      }
    ],
    "family_friendly": true
  },
  "mixed": {
    "type": "mixed",
    "main": [
      {"type": "web", "index": 0, "all": false},
      {"type": "web", "index": 1, "all": false},
      {"type": "videos", "all": true}
    ],
    "top": [],
    "side": []
  },
  "videos": { "...": "..." },
  "news": { "...": "..." },
  "rich": {
    "type": "rich",
    "hint": {
      "vertical": "weather",
      "callback_key": "<callback_key_hex>"
    }
  }
}
```

### Mixed Response

The `mixed` object defines the preferred display order of results across types. It contains three arrays:

| Array | Purpose |
|--|--|
| `main` | Primary result list (ordered sequence of results to display) |
| `top` | Results to display above main results |
| `side` | Results to display alongside main results (e.g., infobox) |

Each entry is a `ResultReference` with `type` (e.g., `"web"`, `"videos"`), `index` (into the corresponding result array), and `all` (`true` to include all results of that type at this position).

## Search Operators

| Operator | Syntax | Description |
|--|--|--|
| Site | `site:example.com` | Limit results to a specific domain |
| File extension | `ext:pdf` | Results with a specific file extension |
| File type | `filetype:pdf` | Results created in a specific file type |
| In title | `intitle:python` | Pages with term in the title |
| In body | `inbody:tutorial` | Pages with term in the body |
| In page | `inpage:guide` | Pages with term in title or body |
| Language | `lang:es` | Pages in a specific language (ISO 639-1) |
| Location | `loc:us` | Pages from a specific country (ISO 3166-1 alpha-2) |
| Include | `+term` | Force inclusion of a term |
| Exclude | `-term` | Exclude pages containing the term |
| Exact match | `"exact phrase"` | Match the exact phrase in order |
| AND | `term1 AND term2` | Both terms required (uppercase) |
| OR / NOT | `term1 OR term2`, `NOT term` | Logical operators (uppercase) |

Set `operators=false` to disable operator parsing.

## Goggles (Custom Ranking) — Unique to Brave

Goggles let you **re-rank search results** — boost trusted sources, suppress SEO spam, or build focused search scopes.

| Method | Example |
|--|--|
| **Hosted** | `--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/rust_programming.goggle"` |
| **Inline** | `--data-urlencode 'goggles=$discard\n$site=example.com'` |

> **Hosted** goggles must be on GitHub/GitLab, include `! name:`, `! description:`, `! author:` headers, and be registered at https://search.brave.com/goggles/create. **Inline** rules need no registration.

**Syntax**: Rules start with `$` + comma-separated options. **Actions** (pick one): `discard`, `boost[=N]`, `downrank[=N]` — N is an integer 1–10. **Site filter**: `site=DOMAIN`. Example: `$site=example.com,boost=3`. Separate rules with `\n` (`%0A`).

**Allow list**: `$discard\n$site=docs.python.org\n$site=developer.mozilla.org` — **Block list**: `$discard,site=pinterest.com\n$discard,site=quora.com`

**Resources**: [Discover](https://search.brave.com/goggles/discover) · [Syntax](https://search.brave.com/help/goggles) · [Quickstart](https://github.com/brave/goggles-quickstart)

## Rich Data Enrichments

For queries about weather, stocks, sports, currency, etc., use the rich callback workflow:

```bash
# 1. Search with rich callback enabled
curl -s "https://api.search.brave.com/res/v1/web/search?q=weather+san+francisco&enable_rich_callback=true" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# Response includes: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. Get rich data with the callback key
curl -s "https://api.search.brave.com/res/v1/web/rich?callback_key=abc123..." \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"
```

**Supported Rich Types**: Calculator, Definitions, Unit Conversion, Unix Timestamp, Package Tracker, Stock, Currency, Cryptocurrency, Weather, American Football, Baseball, Basketball, Cricket, Football/Soccer, Ice Hockey, Web3, Translator

### Rich Callback Endpoint

```http
GET https://api.search.brave.com/res/v1/web/rich
```

| Parameter | Type | Required | Description |
|--|--|--|--|
| `callback_key` | string | Yes | Callback key from the web search `rich.hint.callback_key` field |

## Use Cases

- **General-purpose search integration**: Richest result set (web, news, videos, discussions, FAQ, infobox, locations) in one call. For RAG/LLM grounding, prefer `llm-context`.
- **Structured data extraction**: Products, recipes, ratings, articles via `schemas` and typed fields on results.
- **Custom search with Goggles**: Unique to Brave. Boost/discard sites with inline rules or hosted Goggles for fully customized ranking.

## Notes

- **Pagination**: Use `offset` (0-9) with `count` to page through results
- **Count**: Max 20 for web search; actual results may be less than requested

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions
npx skills add brave/brave-search-skills --skill web-search

Requires BRAVE_SEARCH_API_KEY, sent as the X-Subscription-Token header. Get one at https://api.search.brave.com.

Example Usage

Use the web-search skill to pull this month's coverage of the topic, restricted with a Goggle to primary sources, and give me the URLs with snippets.

Description

Brave publishes a set of official skills for its Search API, and this is the primary one: the web-search endpoint, documented for an agent rather than for a human browsing reference docs.

What it gives an agent

Ranked web results with snippets, URLs and thumbnails, plus the full parameter surface — country, search_lang, count, pagination, safesearch, and freshness filters for restricting results to the past day, week, month or year. Search operators and result-filter values are documented with worked cURL examples, and the response schema is spelled out field by field with a full JSON example, so an agent can parse results without guessing at shapes.

Goggles

The part that has no equivalent elsewhere is Goggles: a custom re-ranking layer that lets you bias Brave's index towards or away from particular sources for a given query. For an agent doing research, that is the difference between "search the web" and "search the sources I trust", and the skill documents how to apply one.

Rich enrichments

A two-step callback flow returns structured data for verticals such as weather: the first search response carries a rich hint with a callback key, and a second request against the rich endpoint exchanges that key for the structured payload.

Requirements

A Brave Search API key (X-Subscription-Token), available from api.search.brave.com; web search is included in the Search plan. The skill sits alongside Brave's other official skills for news, image, video and local POI search, autocomplete, spellcheck, AI answers, pre-extracted LLM context and the bx CLI. MIT licensed.

Related Skills

Skill: Google Workspace CLI (gws)

by Google Workspace

New

Google's official skill for the gws CLI — drive Gmail, Drive, Calendar, Sheets, Docs, Chat and Admin APIs from an agent, with Model Armor screening.

Development
4 views 1 copies

Skill: Netlify Database

by Netlify

New

Netlify's official skill for zero-config managed Postgres — querying from Functions, Drizzle setup, migrations and per-preview database branches.

Development
3 views

Skill: WordPress Block Development

by WordPress

New

Official WordPress skill for Gutenberg block work: block.json, attributes and serialization, dynamic rendering, and the deprecation path that keeps existing content valid.

Development
2 views

Skill: claude-mem

by thedotmack

New

Persistent cross-session memory for coding agents: hooks capture each session, a local SQLite + vector store compresses it, and a mem-search skill reads it back.

Development
1 views
Browse all skills →