Get similar documents with GET

Retrieve documents similar to a reference document identified by its id.

Useful for “more like this” or recommendations.

GET /indexes/{index_uid}/similar

cURL

cURL

curl \
  -X GET 'MEILISEARCH_URL/indexes/INDEX_NAME/similar?id=TARGET_DOCUMENT_ID&embedder=EMBEDDER_NAME' \
  -H 'Authorization: Bearer API_KEY'

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
    }
  ],
  "id": "143",
  "offset": 0,
  "limit": 2,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35
}

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

index_uid · string · required

Unique identifier of the index.

Query Parameters

id · string · required

The unique identifier (primary key value) of the target document. Meilisearch will find and return documents that are semantically similar to this document based on their vector embeddings. This is a required parameter.

embedder · string · required

The name of the embedder to use for finding similar documents. This must match one of the embedders configured in your index settings. The embedder determines how document similarity is calculated based on vector embeddings.

offset · integer · default: 0

Number of similar documents to skip in the response. Use together with limit for pagination through large result sets. For example, to get similar documents 21-40, set offset=20 and limit=20. Defaults to 0.

Required range: x >= 0

limit · integer · default: 20

Maximum number of similar documents to return in a single response. Use together with offset for pagination. Higher values return more results but may increase response time. Defaults to 20.

Required range: x >= 0

attributes_to_retrieve · string[]

Comma-separated list of document attributes to include in the response. Use * to retrieve all attributes. By default, all attributes listed in the displayedAttributes setting are returned. Example: title,description,price.

retrieve_vectors · boolean

When true, includes the vector embeddings for each returned document. Useful for debugging or when you need to inspect the vector data. Note that this can significantly increase response size. Defaults to false.

filter · string

Filter expression to narrow down which documents can be returned as similar. Uses the same syntax as search filters. Only documents matching this filter will be considered when finding similar documents. Example: genres = action AND year > 2000.

show_ranking_score · boolean

When true, includes a global _rankingScore field in each document showing how similar it is to the target document. The score is a value between 0 and 1, where higher values indicate greater similarity. Defaults to false.

show_ranking_score_details · boolean

When true, includes a detailed _rankingScoreDetails object in each document breaking down how the similarity score was calculated. Useful for debugging and understanding why certain documents are considered more similar. Defaults to false.

show_performance_details · boolean

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

ranking_score_threshold · number<float>

Minimum ranking score threshold (between 0.0 and 1.0) that documents must meet to be included in results. Documents with a similarity score below this threshold will be excluded. Useful for ensuring only highly similar documents are returned.

Response

200

application/json

The documents are returned.

Option 1

Option 2

Response containing similar documents

hitsPerPage · integer · required

Number of results per page.

Required range: x >= 0

page · integer · required

Current page index (1-based).

Required range: x >= 0

totalPages · integer · required

Exhaustive total number of result pages.

Required range: x >= 0

totalHits · integer · required

Exhaustive total number of matching documents.

Required range: x >= 0

hits · object[] · required

Results of the query

Show child attributes

id · string · required

Document ID that was used as reference

processingTimeMs · integer · required

Processing time of the query in milliseconds

Required range: x >= 0

performanceDetails · any

Performance details of the query