web-search
USE FOR web search. Returns ranked results with snippets, URLs, thumbnails. Supports freshness filters, SafeSearch, Goggles for custom ranking, pagination. Primary search endpoint.
- Installs
- 4.7K
- Last 24h
- +9
- Trending rank
- #9296
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/brave/brave-search-skills --skill web-search- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads web-search automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
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
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
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
# 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-Longtake 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
{
"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 · Syntax · Quickstart
Rich Data Enrichments
For queries about weather, stocks, sports, currency, etc., use the rich callback workflow:
# 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
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
schemasand 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) withcountto page through results - Count: Max 20 for web search; actual results may be less than requested
FAQ
What does the web-search skill do?
USE FOR web search. Returns ranked results with snippets, URLs, thumbnails. Supports freshness filters, SafeSearch, Goggles for custom ranking, pagination. Primary search endpoint.
How do I install web-search?
Run npx skills add https://github.com/brave/brave-search-skills --skill web-search in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/web-search/ (personal) or .claude/skills/web-search/ (project).
Which AI agents can use web-search?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is web-search safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains web-search?
It is published by brave in brave/brave-search-skills, and it is an official skill from the maker of the technology it covers. It has 4,684 recorded installs.
More from brave/brave-search-skills
images-search
brave/brave-search-skills
USE FOR image search. Returns images with title, source URL, thumbnail. Supports SafeSearch filter. Up to 200 results.
news-search
brave/brave-search-skills
USE FOR news search. Returns news articles with title, URL, description, age, thumbnail, profile. Supports freshness and date range filtering, SafeSearch filter and Goggles for custom ranking.
llm-context
brave/brave-search-skills
USE FOR RAG/LLM grounding. Returns pre-extracted web content (text, tables, code) optimized for LLMs. GET + POST. Adjust maxtokens/count based on complexity. Supports Goggles, local/POI. For AI answers use answers. Recommended for anyone building AI/agentic applications.
videos-search
brave/brave-search-skills
USE FOR video search. Returns videos with title, URL, thumbnail, duration, view count, creator. Supports freshness filters, SafeSearch, pagination.
answers
brave/brave-search-skills
USE FOR AI-grounded answers via OpenAI-compatible /chat/completions. Two modes: single-search (fast) or deep research (enableresearch=true, thorough multi-search). Streaming/blocking. Citations.
local-pois
brave/brave-search-skills
USE FOR getting local business/POI details. Requires POI IDs from local-place-search, or from web-search with resultfilter=locations. Returns full business information including ratings, hours, contact info. Max 20 IDs.
Popular productivity & automation skills
agent-browser
vercel-labs/agent-browser
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.
lark-doc
open.feishu.cn
飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；/page/ 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。
lark-base
open.feishu.cn
飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。
lark-drive
open.feishu.cn
飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。
lark-shared
open.feishu.cn
Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.
lark-im
open.feishu.cn
飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。