Name: web-search
Author: brave

SKILL.md

$2a

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

US

Search country (2-letter country code or ALL)

search_lang

string

en

Language preference (2+ char language code)

ui_lang

string

en-US

UI language (e.g., "en-US")

count

int

20

Max results per page (1-20)

offset

int

0

Page offset for pagination (0-9)

safesearch

string

moderate

Adult content filter (off/moderate/strict)

freshness

string

Time filter (pd/pw/pm/py or date range)

text_decorations

bool

true

Include highlight markers

spellcheck

bool

true

Auto-correct query

result_filter

string

Filter result types (comma-separated)

goggles

string

Custom ranking filter (URL or inline)

extra_snippets

bool

Get up to 5 extra snippets per result

operators

bool

true

Apply search operators

units

string

Measurement units (metric/imperial)

enable_rich_callback

bool

false

Enable rich 3rd party data callback

include_fetch_metadata

bool

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 "...&#x26;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

{

  "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: $boost=N / $downrank=N (1–10), $discard, $site=example.com. Combine with commas: $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&#x26;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 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

web-search

SKILL.md

With Parameters

Endpoint

When to Use Web Search

Parameters

Freshness Values

Result Filter Values

Location Headers (Optional)

Response Format

Response Fields

JSON Example

Mixed Response

Search Operators

Goggles (Custom Ranking) — Unique to Brave

Rich Data Enrichments

Rich Callback Endpoint

Use Cases

Notes

Let your agent run on any real-world website

Related skills

Stop writing automation&scrapers