Search with POST
Search for documents matching a query in the given index.
Equivalent to the search with GET route in the Meilisearch API.
Authorizations
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:
-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:
const client = new MeiliSearch({
host: 'MEILISEARCH_URL',
apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});Path Parameters
Unique identifier of the index.
Body
Sets the search terms.
Meilisearch returns documents that match this query.
The query supports prefix search and typo tolerance.
Meilisearch only considers the first ten words; terms are normalized (lowercase, accents ignored).
Omit or leave empty for a placeholder search: no query terms are applied, so Meilisearch returns all searchable documents in the index, ordered by ranking rules.
Enclose terms in double quotes (") for phrase search: only documents containing that exact sequence of words are returned (e.g. "Winter Feast").
Use a minus sign (-) before a word or phrase to exclude it from results.
Number of documents to skip at the start of the results.
Use together with limit for pagination (e.g. offset=20 and limit=20 returns results 21–40).
This parameter is ignored when page or hitsPerPage is set; in that case the response includes totalHits and totalPages instead of estimatedTotalHits.
x >= 0Maximum number of documents to return in the response.
Use with offset for pagination.
This parameter is ignored when page or hitsPerPage is set. The value cannot exceed the index maxTotalHits setting.
x >= 0Request a specific results page (1-indexed).
Use together with hitsPerPage.
When this parameter is set, the response includes totalHits and totalPages instead of estimatedTotalHits.
page and hitsPerPage take precedence over offset and limit.
x >= 0Maximum number of documents per page for pagination.
This value determines totalPages; use it together with page.
When set, the response includes totalHits and totalPages.
Set to 0 to obtain the exhaustive totalHits count without returning any documents.
x >= 0List of attributes to include in each returned document.
Use ["*"] to return all attributes; if not set, the index displayed attributes list is used.
Attributes that are not in displayedAttributes are omitted from the response.
Attributes whose values should be cropped to a short excerpt.
The cropped text appears in each hit's _formatted object.
Length is controlled by cropLength, or you can override it per attribute with the attribute:length syntax.
Use ["*"] to crop all attributes in attributesToRetrieve.
When possible, the crop is centered around the matching terms.
Maximum number of words to include in cropped values.
This parameter only applies when attributesToCrop is set.
Both query terms and stop words count toward this length.
x >= 0String used to mark crop boundaries in cropped text.
If null or empty, no markers are inserted.
Markers are only added where content was actually removed.
Attributes in which matching query terms should be highlighted.
The highlighted text appears in each hit's _formatted object.
Use ["*"] to highlight in all attributes from attributesToRetrieve.
By default, matches are wrapped in <em> and </em>; you can override this with highlightPreTag and highlightPostTag.
Highlighting also applies to synonyms and stop words.
Supported value types are string, number, array, and object.
String to insert before each highlighted term.
Can be any string (e.g. <strong>, *).
If null or empty, nothing is inserted at the start of a match.
String to insert after each highlighted term.
Should be used together with highlightPreTag to avoid malformed output (e.g. unclosed HTML tags).
When true, each hit includes a _matchesPosition object with the byte offset (start and length) of each matched term.
This is useful when you need custom highlighting.
Note that positions are given in bytes, not characters.
A filter expression to narrow results.
All attributes used in the expression must be in filterableAttributes.
You can pass a string (e.g. "(genres = horror OR genres = mystery) AND director = 'Jordan Peele'") or an array (e.g. [["genres = horror", "genres = mystery"], "director = 'Jordan Peele'"]).
For geo search, use _geoRadius(lat, lng, distance_in_meters), _geoBoundingBox([lat,lng],[lat,lng]), or _geoPolygon([lat,lng], ...) (GeoJSON only for polygon).
Sort results by one or more attributes and their order.
Use the format ["attribute:asc", "attribute:desc"]; only attributes in sortableAttributes can be used.
For geo search, use _geoPoint(lat,lng):asc or :desc; the response then includes _geoDistance in meters.
The first attribute in the list has precedence.
Return only one document per distinct value of the given attribute (e.g. deduplicate by product_id).
The attribute must be in filterableAttributes.
This overrides the index distinctAttribute setting for this request.
See distinct attribute.
Return the count of matches per facet value for the listed attributes.
The response includes facetDistribution and, for numeric facets, facetStats (min/max).
Use ["*"] to request counts for all filterableAttributes.
The number of values returned per facet is limited by the index maxValuesPerFacet setting; attributes not in filterableAttributes are ignored.
More info: faceting.
How to match query terms when there are not enough results to satisfy limit.
last: Returns documents containing all query terms first. If there are not enough such results, Meilisearch removes one query term at a time, starting from the end of the query (e.g. for "big fat cat", then "big fat", then "big").
all: Only returns documents that contain all query terms. Meilisearch does not relax the query even if fewer than limit documents match.
frequency: Returns documents containing all query terms first. If there are not enough, removes one term at a time starting with the word that is most frequent in the dataset, giving more weight to rarer terms (e.g. in "white cotton shirt", prioritizes documents containing "white" if "shirt" is very common).
Default: last.
last, all, frequency Restrict the search to the listed attributes only.
Each attribute must be in the index searchable attributes list.
The order of attributes in this parameter does not affect relevancy.
Exclude from the results any document whose ranking score is below this value (between 0.0 and 1.0).
Excluded hits do not count toward estimatedTotalHits, totalHits, or facet distribution.
When used together with page and hitsPerPage, this parameter may reduce performance because Meilisearch must score all matching documents.
Explicitly specify the language(s) of the query.
Pass an array of supported ISO-639 locales.
This overrides auto-detection; use it when auto-detection is wrong for the query or the documents.
See also the localizedAttributes settings and Language.
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 Hybrid search: combines keyword and semantic search.
The embedder field (required) must match an embedder name in index settings.
The semanticRatio field controls the balance: 0.0 means keyword-only results, 1.0 means semantic-only.
When q is empty and semanticRatio is greater than 0, Meilisearch performs a pure semantic search.
Custom query vector for vector or hybrid search.
The array length must match the dimensions of the embedder configured in the index.
This parameter is mandatory when using a user-provided embedder.
When used with hybrid, documents are ranked by vector similarity.
You can also use it to override an embedder's automatic vector generation.
When true, the response includes document and query embeddings in each hit's _vectors field.
The _vectors field must be listed in displayedAttributes for it to appear.
For multimodal search: provide data (e.g. image, text) that populates a single search fragment configured in index settings.
A search fragment is a named slot that defines which media or fields are sent to the embedder.
An embedder is required; this parameter is incompatible with vector.
POST only.
Personalized search: provide an object with a userContext field (a string describing the user, e.g. preferences or behavior).
Results are then tailored to that profile.
Personalization must be enabled (e.g. Cohere key for self-hosted instances).
When true, runs the query on the whole network (all shards covered, documents deduplicated across remotes).
When false or omitted, the query runs locally.
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 or omitted = local (default).
When using the network, the index must exist with compatible settings on all remotes.
Documents with the same id are assumed identical for deduplication.
When true, each document includes a _rankingScore between 0.0 and 1.0; a higher value means the document is more relevant.
See ranking score.
The sort ranking rule does not affect the value of _rankingScore.
When true, each document includes _rankingScoreDetails, which breaks down the score contribution of each ranking rule.
Useful for debugging relevancy.
When true, the response includes a performanceDetails object with a timing breakdown of the query processing.
Response
The documents are returned.
- Option 1
- Option 2
Search response containing matching documents and metadata.
Number of results per page.
x >= 0Current page index (1-based).
x >= 0Exhaustive total number of result pages.
x >= 0Exhaustive total number of matching documents.
x >= 0Matching documents.
Each hit contains document fields and, when requested, _formatted, _matchesPosition, _rankingScore, _rankingScoreDetails, _geoDistance.
Query string that produced this response.
Time taken to process the query, in milliseconds.
x >= 0Query embedding used for the search.
Present when vector or hybrid search was used.
Count of matching documents per facet value for each requested facet.
Present when facets was set.
Minimum and maximum numeric values per facet.
Present for numeric facets when facets was set.
UUID v7 identifying this search request.
Query and index metadata.
Present when requested via the Meili-Include-Metadata header.
Timing breakdown per processing step.
Present when showPerformanceDetails was true.
Errors from remote shards. Federated search only.
Exhaustive number of semantic search matches.
AI-powered (hybrid/semantic) searches only.
x >= 0