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.
Specification
- Skill ID
- brave/brave-search-skills/web-search
- Publisher
- brave
- Repository
- brave-search-skills
- Installs
- 0
- Files
- 1
- Synced
- Sep 23, 2026
How to use it
Open any RiverX project, open the Skills panel in the chat, and search for this identifier. The files are fetched from the source repository at install time.
brave/brave-search-skills/web-searchInstalls these files- SKILL.md
What this skill tells the agent
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/searchNote: 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 |
More from brave
Use this skill in a project
Open any RiverX project, search the Skills panel for brave/brave-search-skills/web-search, and install it in one click.