Suggest / Autocomplete

Requires API Key

Get one at

https://api.search.brave.com

Plan

Included in the

Suggest

plan. See

https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quick Start (cURL)

Basic Suggestions

curl

-s

"https://api.search.brave.com/res/v1/suggest/search?q=how+to+"

\

-H

"Accept: application/json"

\

-H

"X-Subscription-Token:

${BRAVE_SEARCH_API_KEY}

"

With All Parameters

curl

-s

"https://api.search.brave.com/res/v1/suggest/search"

\

-H

"Accept: application/json"

\

-H

"X-Subscription-Token:

${BRAVE_SEARCH_API_KEY}

"

\

-G

\

--data-urlencode

"q=albert"

\

--data-urlencode

"country=US"

\

--data-urlencode

"lang=en"

\

--data-urlencode

"count=10"

\

--data-urlencode

"rich=true"

Endpoint

GET https://api.search.brave.com/res/v1/suggest/search

Authentication

:

X-Subscription-Token:

header

Optional Headers

:

Accept-Encoding: gzip

— Enable response compression

Parameters

Parameter

Type

Required

Default

Description

q

string

Yes

—

Suggest search query (1-400 chars, max 50 words)

lang

string

No

en

Language preference (2+ char language code, e.g.

fr

,

de

,

zh-hans

)

country

string

No

US

Search country (2-letter country code or

ALL

)

count

int

No

5

Number of suggestions (1-20). Actual results may be fewer

rich

bool

No

false

Enhance with entity info (title, description, image). Paid Search plan required

Response Fields

Field

Type

Description

type

string

Always

"suggest"

query.original

string

The original suggest search query

results

array

List of suggestions (may be empty)

results[].query

string

Suggested query completion

results[].is_entity

bool?

Whether the suggested enriched query is an entity (rich only)

results[].title

string?

The suggested query enriched title (rich only)

results[].description

string?

The suggested query enriched description (rich only)

results[].img

string?

The suggested query enriched image URL (rich only)

Fields with

null

values are excluded from the response. Non-rich results contain only the

query

field.

Rich Response Example (

rich=true

)

{

"type"

:

"suggest"

,

"query"

:

{

"original"

:

"albert"

}

,

"results"

:

[

{

"query"

:

"albert einstein"

,

"is_entity"

:

true

,

"title"

:

"Albert Einstein"

,

"description"

:

"German-born theoretical physicist"

,

"img"

:

"https://imgs.search.brave.com/..."

}

,

{

"query"

:

"albert einstein quotes"

,

"is_entity"

:

false

}

]

}

Use Cases

Search-as-you-type UI

Real-time autocomplete dropdown. Debounce 150-300ms.

Query refinement for RAG

Expand partial/ambiguous queries before calling

web-search

or

llm-context

.

Entity detection

Use

rich=true

to detect entities with title, description, and image for preview cards.

Typo-tolerant input

Get clean suggestions from misspelled input without separate spellcheck.

Notes

Latency

Designed for <100ms response times

Country/lang

Hints for suggestion relevance, not strict filters

Typo handling

Suggestions handle common typos without separate spellcheck