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 With Parameters Endpoint 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 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 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: 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 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