Skip to main content
POST
Web Search

Authorizations

X-BB-API-Key
string
header
required

Body

application/json
provider
default:parallel
required

Search provider to serve this request. Defaults to parallel, which uses advanced mode unless mode is set. If you omit it and parallel can't apply one of your filters, exa serves the request at exa pricing. The response provider field shows which one served it.

Available options:
parallel
query
string
required

The search query string

Required string length: 1 - 200
mode

The search mode used by the underlying provider. Defaults to advanced for parallel and fast for exa. See the Search docs for the available modes.

Available options:
fast
numResults
integer
default:10

Number of results to return

Required range: 1 <= x <= 25
includeDomains
string[]

Only return results from these domains. Entries can be a hostname (example.com), a hostname with a path prefix (example.com/docs), or a wildcard subdomain (*.example.com). The parallel provider allows one list, not both, with at most 200 domains and no scheme, port, query string, or fragment.

Required array length: 1 - 1200 elements
Required string length: 1 - 512
excludeDomains
string[]

Never return results from these domains. Accepts the same entry formats as includeDomains. Not supported with the people category.

Required array length: 1 - 1200 elements
Required string length: 1 - 512
startPublishedDate
string<date-time>

Only return results published after this date-time (RFC 3339, for example 2026-01-01T00:00:00Z). The parallel provider rounds it up to a whole UTC day. Not supported with the company or people categories.

endPublishedDate
string<date-time>

Only return results published before this date-time (RFC 3339, for example 2026-01-01T00:00:00Z). Only the exa provider supports this filter. Not supported with the company or people categories.

category
enum<string>

Focus the search on a category of content. Only the exa provider supports this filter.

Available options:
company,
publication,
news,
personal site,
financial report,
people
userLocation
string

Two-letter ISO 3166-1 country code of the end user. Localizes ranking without restricting results to sources from that country. The parallel provider supports only some countries.

Required string length: 2
Pattern: ^[A-Za-z]{2}$
moderation
boolean

Filter unsafe content from the results. Defaults to false. Only the exa provider supports true.

objective
string

The task intent and soft preferences for the search, in natural language. Adds context to query without replacing it.

Required string length: 1 - 4096
Pattern: \S
maxAgeHours
integer

Refetch a page when the cached copy is older than this many hours. Omit to use the provider default. A provider can return an older cached copy when a live fetch fails.

Required range: 1 <= x <= 720
excerpts
boolean

Return the passages of each page most relevant to the query. Defaults to false.

Response

200 - application/json

The request has succeeded.

requestId
string
required

Unique identifier for the request

query
string
required

The search query that was executed

results
object[]
required

List of search results

provider
enum<string>

The search provider that served the request. Can differ from the documented default when the project or the filters select another provider.

Available options:
parallel,
exa
mode
enum<string>

The search mode that served the request.

Available options:
fast,
advanced,
deep-lite,
deep