Search the public web API

Endpoint facts

Method

POST

API path

/web/search

Auth

apiKey

Credits

34 credits/request

Charged on

Successful 2xx responses only

Platform

Retrieval

Execution

Managed browser rendering where the target needs it

Request body schema

#/definitions/retrievalplatform.WebSearchRequest

How this endpoint behaves

Searches Brave's public web results and can read a bounded number of returned pages. Requires the x-api-key header. A response may contain partial coverage when the source fails; successful hits are retained, with any page-read failure included alongside its hit. Page reads remain within each selected result's public host scope.

Each result page read from the search source costs 3 credits, and a search reads up to 3 result pages (about 20 results each) to reach limit. A limit of up to 20 costs 3 credits, 21 to 40 up to 6, and 41 to 50 up to 9; only result pages that were read successfully are charged. If a later result page fails, the results already collected are returned with partial set to true and a source_failed warning, and only the successful pages are charged. Optional page reads from scrape are priced separately, at 5 credits each. The precheck reserves the worst case: result pages plus scrape_limit page reads, at most 34 credits.

Request body:

• q: required, 1–1000 characters.
• limit: optional, 1–50 results; default 10. Up to limit results are returned by reading further result pages (about 20 results per page, at most 3 pages); fewer are returned when the source has no more distinct results. The effective maximum is also bounded by capabilities.
• country: optional. Result country; defaults to us. Allowed values: all, ar, at, au, be, br, ca, ch, cl, cn, de, dk, es, fi, fr, gb, gr, hk, id, in, it, jp, kr, mx, my, nl, no, nz, ph, pl, pt, ru, sa, se, sg, tr, tw, us, za. Example: us. An unknown value returns a 400 error before any search.
• language: optional. Result language; defaults to en-us. Allowed values: de-de, en-ca, en-gb, en-in, en-us, fi-fi, fr-ca, fr-fr, ja-jp, pt-br, sq-al, sw-ke, zh-tw. Example: en-us. An unknown value returns a 400 error before any search.
• include_domains, exclude_domains: optional, up to 20 unique hostnames each, at most 256 characters per value. The lists may not overlap.
• scrape: optional object with render, only_main_content, max_age, and wait_for fields. render values are auto, http, browser; auto is the default and uses the available HTTP reader in P1. Only auto and http are available; browser returns 503. only_main_content defaults to true. max_age is in milliseconds from 0 to 604800000, default 86400000; wait_for is in milliseconds from 0 to 10000, default 0, and is only valid with render=browser.
• scrape_limit: optional, 1–5 pages, default 3 when scraping is requested. Reject it when scrape is absent.
• max_credits: optional positive integer budget for result-page queries and page reads. It must cover at least one result page (3 credits). A result page that the budget cannot cover is not read; the response is then partial with a budget warning and returns the results already collected.

Response enum values:

• coverage[].status: ok, failed, not_indexed, unsupported.
• coverage[].failure.reason and items[].fetch_failure.reason: invalid_url, unsupported_content_type, blocked, not_found, rate_limited, timeout, upstream_error, internal_error, out_of_scope, robots_disallowed, duplicate, limit_reached, unsupported_filter, unknown_source, idempotency_conflict, invalid_cursor, result_expired, full_text_unavailable, budget_exhausted.
• warnings[].code: source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, cached_source_stale.
• Embedded document passages[].locator is descriptive; it has no enum fields.

Example request:

{
  "q": "Go context cancellation",
  "limit": 5,
  "country": "us",
  "language": "en-us",
  "scrape": {"render": "http"},
  "scrape_limit": 2
}

Shared guides

Related