Search with POST

Search for documents matching a query in the given index.

Equivalent to the search with GET route in the Meilisearch API.

POST /indexes/{indexUid}/search

cURL

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "american ninja" }'

200

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
      "release_date": 1418256000
    }
  ],
  "offset": 0,
  "limit": 2,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35,
  "query": "american "
}

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:

-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

indexUid · string · required

Unique identifier of the index.

Body

application/json

q · string | null

Query string

vector · number<float>[] | null

Search using a custom query vector

media · any

Perform AI-powered search queries with multimodal content

hybrid · object

Hybrid search configuration combining keyword and semantic search. Set semanticRatio to balance between keyword matching (0.0) and semantic similarity (1.0). Requires an embedder to be configured.

Show child attributes

offset · integer · default: 0

Number of documents to skip

Required range: x >= 0

limit · integer · default: 20

Maximum number of documents returned

Required range: x >= 0

page · integer | null

Request a specific page of results

Required range: x >= 0

hits_per_page · integer | null

Maximum number of documents returned for a page

Required range: x >= 0

attributes_to_retrieve · string[] | null

Attributes to display in the returned documents

retrieve_vectors · boolean

Return document and query vector data

attributes_to_crop · string[] | null

Attributes whose values have to be cropped

crop_length · integer · default: 10

Maximum length of cropped value in words

Required range: x >= 0

attributes_to_highlight · string[] | null

Highlight matching terms contained in an attribute

show_matches_position · boolean

Return matching terms location

show_ranking_score · boolean

Display the global ranking score of a document

show_ranking_score_details · boolean

Adds a detailed global ranking score field

show_performance_details · boolean

Adds a detailed performance details field

use_network · boolean | null

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.

filter · any

Filter queries by an attribute's value

sort · string[] | null

Sort search results by an attribute's value

distinct · string | null

Restrict search to documents with unique values of specified attribute

facets · string[] | null

Display the count of matches per facet

highlight_pre_tag · string · default: <em>

String inserted at the start of a highlighted term

highlight_post_tag · string · default: </em>

String inserted at the end of a highlighted term

crop_marker · string · default: …

String marking crop boundaries

matching_strategy · enum<string>

Strategy used to match query terms within documents

Available options: last, all, frequency

attributes_to_search_on · string[] | null

Restrict search to the specified attributes

ranking_score_threshold · number<double> | null

Minimum ranking score threshold (0.0 to 1.0) that documents must achieve to be included in results. Documents with scores below this threshold are excluded. Useful for filtering out low-relevance results.

locales · enum<string>[] | null

Explicitly specify languages used in a query

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

personalize · object

Enables personalized search results based on user context. When provided, the search uses AI to tailor results to the user's profile, preferences, or behavior described in userContext.

Show child attributes

Response

200

application/json

The documents are returned.

Option 1

Option 2

Search response containing matching documents and metadata

hitsPerPage · integer · required

Number of results on each page

Required range: x >= 0

page · integer · required

Current search results page

Required range: x >= 0

totalPages · integer · required

Exhaustive total number of search result pages

Required range: x >= 0

totalHits · integer · required

Exhaustive total number of matches

Required range: x >= 0

hits · object[] · required

Results of the query

Show child attributes

query · string · required

Query originating the response

processingTimeMs · integer · required

Processing time of the query in milliseconds

Required range: x >= 0

queryVector · number<float>[] | null

Vector representation of the query

facetDistribution · object

Distribution of the given facets

Show child attributes

facetStats · object

The numeric min and max values per facet

Show child attributes

requestUid · string<uuid> | null

A UUID v7 identifying the search request

metadata · object

Metadata about the search query

Show child attributes

performanceDetails · any

Performance details of the search query

remoteErrors · object

Show child attributes

semanticHitCount · integer<u-int32> | null

Exhaustive number of semantic search matches (only present in AI-powered searches)

Required range: x >= 0