Fetch the items that are most relevant to your user.

This endpoint returns the ranked results for your trained ranking model. Contrary to the GET version of the rank call, this POST method requires parameters to be fed through the request body. It takes in 4 optional parameters:

  • user_id - the user id to personalize for.
  • limit - the number of items to return in the response.
  • interactions - an array of the user's latest positive interactions in chronological order. These interactions allow you to implement session based ranking (see design for more info).
  • retrieval - a dictionary describing your retrieval query. The retrieval query language is explained in more detail on the design page.

Example call:

curl --location --request POST 'https://api.prod.shaped.ai/v0/models/{model_name}/rank' \
--header 'x-api-key: {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user-1",
    "limit": 20,
    "interactions": [
      {"item_id": "item-1"},
      {"item_id": "item-2"},
      {"item_id": "item-3"}
    "retrieval": {
      "genre": {"$in": ["genre-1", "genre-2"]}

The result is a list of item_ids ordered by relevance.


This endpoint maintains an average 200ms latency and is suitable for real-time usage within your product.