Skip to main content
The /similar route uses AI-powered search to return a number of documents similar to a target document. Meilisearch exposes two routes for retrieving similar documents: POST and GET. In the majority of cases, POST will offer better performance and ease of use.

​
Get similar documents with POST

POST
/indexes/{index_uid}/similar
Retrieve documents similar to a specific search result.

​
Path parameters

NameTypeDescription
index_uid *Stringuid of the requested index

​
Body

ParameterTypeDefault valueDescription
idString or numbernullIdentifier of the target document (mandatory)
embedderStringnullEmbedder to use when computing recommendations. Mandatory
attributesToRetrieveArray of strings["*"]Attributes to display in the returned documents
offsetInteger0Number of documents to skip
limitInteger20Maximum number of documents returned
filterStringnullFilter queries by an attribute’s value
showRankingScoreBooleanfalseDisplay the global ranking score of a document
showRankingScoreDetailsBooleanfalseDisplay detailed ranking score information
rankingScoreThresholdNumbernullExclude results with low ranking scores
retrieveVectorsBooleanfalseReturn document vector data

​
Example

curl \  -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/similar' \  -H 'Content-Type: application/json' \  -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \  --data-binary '{  "id": TARGET_DOCUMENT_ID,  "embedder": "EMBEDDER_NAME"  }'

​
Response: 200 OK

{  "hits": [  {  "id": "299537",  "title": "Captain Marvel"  },  {  "id": "166428",  "title": "How to Train Your Dragon: The Hidden World"  }  {  "id": "287947",  "title": "Shazam!"  }  ],  "id": "23",  "processingTimeMs": 0,  "limit": 20,  "offset": 0,  "estimatedTotalHits": 3 }

​
Get similar documents with GET

GET
/indexes/{index_uid}/similar
Retrieve documents similar to a specific search result.

​
Path parameters

NameTypeDescription
index_uid *Stringuid of the requested index

​
Query parameters

ParameterTypeDefault valueDescription
idString or numbernullIdentifier of the target document (mandatory)
embedderString"default"Embedder to use when computing recommendations. Mandatory
attributesToRetrieveArray of strings["*"]Attributes to display in the returned documents
offsetInteger0Number of documents to skip
limitInteger20Maximum number of documents returned
filterStringnullFilter queries by an attribute’s value
showRankingScoreBooleanfalseDisplay the global ranking score of a document
showRankingScoreDetailsBooleanfalseDisplay detailed ranking score information
rankingScoreThresholdNumbernullExclude results with low ranking scores
retrieveVectorsBooleanfalseReturn document vector data

​
Example

curl \  -X GET 'MEILISEARCH_URL/indexes/INDEX_NAME/similar?id=TARGET_DOCUMENT_ID&embedder=EMBEDDER_NAME'

​
Response: 200 OK

{  "hits": [  {  "id": "299537",  "title": "Captain Marvel"  },  {  "id": "166428",  "title": "How to Train Your Dragon: The Hidden World"  }  {  "id": "287947",  "title": "Shazam!"  }  ],  "id": "23",  "processingTimeMs": 0,  "limit": 20,  "offset": 0,  "estimatedTotalHits": 3 }