Search with GET

Search for documents matching a query in the given index.

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

GET /indexes/{indexUid}/search

cURL

cURL

curl \
  -X GET 'MEILISEARCH_URL/indexes/movies/search?q=american%20ninja'

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.

Query Parameters

q · string

The search query string. Meilisearch will return documents that match this query. Supports prefix search (words matching the beginning of the query) and typo tolerance. Leave empty to match all documents.

vector · number<float>[]

A vector of floating-point numbers for semantic/vector search. The dimensions must match the embedder configuration. When provided, documents are ranked by vector similarity. Can be combined with q for hybrid search.

offset · integer · default: 0

Number of search results to skip. Use together with limit for pagination. For example, to get results 21-40, set offset=20 and limit=20. Defaults to 0. Cannot be used with page/hitsPerPage.

Required range: x >= 0

limit · integer · default: 20

Maximum number of search results to return. Use together with offset for pagination. Defaults to 20. Cannot be used with page/hitsPerPage.

Required range: x >= 0

page · integer

Request a specific page of results (1-indexed). Use together with hitsPerPage for page-based pagination. Cannot be used with offset/limit.

Required range: x >= 0

hitsPerPage · integer

Number of results per page when using page-based pagination. Use together with page. Cannot be used with offset/limit.

Required range: x >= 0

attributesToRetrieve · string[]

Comma-separated list of attributes to include in the returned documents. Use * to return all attributes. By default, returns attributes from the displayedAttributes setting.

retrieveVectors · boolean

When true, includes vector embeddings in the response for documents that have them. Defaults to false.

attributesToCrop · string[]

Comma-separated list of attributes whose values should be cropped to fit within cropLength. Useful for displaying long text attributes in search results. Format: attribute or attribute:length.

cropLength · integer · default: 10

Maximum number of words to keep when cropping attribute values. The cropped text will be centered around the matching terms. Defaults to 10.

Required range: x >= 0

attributesToHighlight · string[]

Comma-separated list of attributes whose matching terms should be highlighted with highlightPreTag and highlightPostTag. Use * to highlight all searchable attributes.

filter · string

Filter expression to narrow down search results. Uses SQL-like syntax. Example: genres = action AND rating > 4. Only attributes in filterableAttributes can be used.

sort · string

Comma-separated list of attributes to sort by. Format: attribute:asc or attribute:desc. Only attributes in sortableAttributes can be used. Custom ranking rules can also affect sort order.

distinct · string

Attribute used to ensure only one document with each unique value is returned. Useful for deduplication. Only attributes in filterableAttributes can be used.

showMatchesPosition · boolean

When true, returns the position (start and length) of each matched term in the original document attributes. Useful for custom highlighting implementations.

showRankingScore · boolean

When true, includes a _rankingScore field (0.0 to 1.0) in each document indicating how well it matches the query. Higher scores mean better matches.

showRankingScoreDetails · boolean

When true, includes a _rankingScoreDetails object showing the contribution of each ranking rule to the final score. Useful for debugging relevancy.

showPerformanceDetails · boolean

When true, includes a _performanceDetails object showing the performance details of the search.

facets · string[]

Comma-separated list of attributes for which to return facet distribution (value counts). Only attributes in filterableAttributes can be used. Returns the count of documents matching each facet value.

highlightPreTag · string · default: <em>

HTML tag or string to insert before highlighted matching terms. Defaults to <em>.

highlightPostTag · string · default: </em>

HTML tag or string to insert after highlighted matching terms. Defaults to </em>.

cropMarker · string · default: …

String used to indicate truncated content when cropping. Defaults to … (ellipsis).

matchingStrategy · enum<string>

Strategy for matching query terms. last (default): all terms must match, removing terms from the end if needed. all: all terms must match exactly. frequency: prioritizes matching frequent terms. This is unfortunately a duplication of the struct in <meilisearch/src/search/mod.rs>. The reason why it is duplicated is because milli cannot depend on meilisearch. It would be cyclic imports.

Available options: last, all, frequency

attributesToSearchOn · string[]

Comma-separated list of attributes to search in. By default, searches all searchableAttributes. Use this to restrict search to specific fields for better performance or relevance.

hybridEmbedder · string

Name of the embedder to use for hybrid/semantic search. Must match an embedder configured in the index settings.

hybridSemanticRatio · number<float>

Balance between keyword search (0.0) and semantic/vector search (1.0) in hybrid search. A value of 0.5 gives equal weight to both. Defaults to 0.5.

rankingScoreThreshold · number<float>

Minimum ranking score (0.0 to 1.0) a document must have to be included in results. Documents with lower scores are excluded. Useful for filtering out poor matches.

locales · enum<string>[]

Comma-separated list of language locales to use for tokenization and processing. Useful for multilingual content. Example: en,fr,de.

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

personalizeUserContext · string

User-specific context for personalized search results. The format depends on your personalization configuration.

useNetwork · boolean

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.

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