Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

Path Parameters

index_uid
string
required

Unique identifier of the index.

Body

application/json

Request body for searching facet values

facetName
string
required

Name of the facet attribute to search. Must be present in the index's filterableAttributes list.

facetQuery
string | null

Query string to search for matching facet values. If not specified, Meilisearch returns all facet values for the facetName, limited to 100 results. Note: only the first word is used for matching.

q
string | null

Query string to filter the underlying documents before computing facet values. This affects which facet values appear and their counts, but does not filter the facet values themselves.

vector
number<float>[] | null

Custom query vector for semantic search

media
any

Multimodal content for AI-powered search

hybrid
null | object

Hybrid search configuration that combines keyword search with semantic (vector) search. Set semanticRatio to balance between keyword matching (0.0) and semantic similarity (1.0). Requires an embedder to be configured in the index settings.

filter
any

Filter expression to restrict which documents are considered when computing facet values. Attributes must be in filterableAttributes before they can be used in filters.

matchingStrategy
enum<string>

Strategy used to match query terms

Available options:
last,
all,
frequency
attributesToSearchOn
string[] | null

Restrict search to specified attributes

rankingScoreThreshold
number<double> | null

Minimum ranking score threshold (0.0 to 1.0) that documents must achieve to be considered when computing facet counts. Documents with scores below this threshold are excluded from facet value counts.

locales
enum<string>[] | null

Languages to use for query processing

Available options:
af,
ak,
am,
ar,
az,
be,
bn,
bg,
ca,
cs,
da,
de,
el,
en,
eo,
et,
fi,
fr,
gu,
he,
hi,
hr,
hu,
hy,
id,
it,
jv,
ja,
kn,
ka,
km,
ko,
la,
lv,
lt,
ml,
mr,
mk,
my,
ne,
nl,
nb,
or,
pa,
fa,
pl,
pt,
ro,
ru,
si,
sk,
sl,
sn,
es,
sr,
sv,
ta,
te,
tl,
th,
tk,
tr,
uk,
ur,
uz,
vi,
yi,
zh,
zu,
afr,
aka,
amh,
ara,
aze,
bel,
ben,
bul,
cat,
ces,
dan,
deu,
ell,
eng,
epo,
est,
fin,
fra,
guj,
heb,
hin,
hrv,
hun,
hye,
ind,
ita,
jav,
jpn,
kan,
kat,
khm,
kor,
lat,
lav,
lit,
mal,
mar,
mkd,
mya,
nep,
nld,
nob,
ori,
pan,
pes,
pol,
por,
ron,
rus,
sin,
slk,
slv,
sna,
spa,
srp,
swe,
tam,
tel,
tgl,
tha,
tuk,
tur,
ukr,
urd,
uzb,
vie,
yid,
zho,
zul,
cmn
exhaustiveFacetCount
boolean | null

Return exhaustive facet count instead of an estimate

useNetwork
boolean | null

When true, runs the query on the whole network (all shards covered exactly once).

When false, the query runs locally.

When omitted or null, the default value depends on whether the sharding is enabled for the instance:

  • If the instance has sharding enabled (has a leader), defaults to true.
  • Otherwise defaults to false.

Enterprise Edition only. This feature is available in the Enterprise Edition.

It also requires the network experimental feature.

Values: true = use the whole network; false = local, default = see above.

When using the network, the index must exist with compatible settings on all remotes.

Response

Facet values matching the query are returned.

Result of a facet search operation.

facetHits
object[]
required

Array of matching facet values with their document counts, sorted lexicographically in ascending order (or by count if sortFacetValuesBy is set to "count").

processingTimeMs
integer
required

Time in milliseconds Meilisearch took to process the request.

Required range: x >= 0
facetQuery
string | null

The original facetQuery from the request. null if no query was provided.

remoteErrors
object | null

Errors from remote shards. Only present in federated search when some remotes failed.