GET /{environment}/recommendations/lists Copy page Copy link View Markdown Description Retrieve a slice of a previously computed ranked list using the list_key from the original recommendation response, including a smart-sorting response. The original request returns the beginning of the list, starting at rank 1. For example, after it returns ranks 1 and 2, request offset=3&limit=2 to retrieve ranks 3 and 4. The list remains available for a limited time. List-page retrieval must be enabled for your environment; contact Froomle if you need it. Parameters Type Name Description Schema Path environment required The environment for which a request is made. string Query limit required Maximum number of items to return, starting at offset. integer Query list_key required String identifier of the previously computed list to request recommended items from. This can be retrieved from the response body of the initial recommendations request. string Query offset required The 1-based rank of the first item to return from the stored list. Use 1 for the first item or 3 for the third item. This is not a page number or the number of items to skip. integer Responses HTTP Code Description Schema 200 OK Recommendations 404 list_key not found, it either expired or never existed No Content Produces application/json Tags recommendations Example HTTP response Response 200 { "device_id" : "the-cookie-id-123", "lists" : [ { "items" : [ { "item_id" : "item_id_3", "rank" : 3 }, { "item_id" : "item_id_4", "rank" : 4 }, { "item_id" : "item_id_5", "rank" : 5 } ], "limit" : 3, "list_key" : "a_unique_list_identifier", "list_name" : "reco_list_001", "list_size" : 5, "offset" : 3 } ], "request_id" : "2141141", "user_group" : "froomle", "user_id" : "customer-user-id-123" } Item One content-item. Name Description Schema information_field optional The Froomle API can be configured to return additional information fields (if present in the item information). Please contact the Froomle support team to set this up. string item_id required The identifier of the recommended item string rank required The item’s position in the complete ranked list. The first item has rank 1. integer ResponseList Contains up to limit items from a ranked list requested with list_size. If a list_key is available, further pages can be requested from the /lists endpoint. Name Description Schema items optional Items returned for this page, up to the requested limit. Fewer items may be returned when fewer eligible recommendations are available. < Item > array limit optional Maximum number of items requested for this page, not the number actually returned. integer list_key optional Opaque identifier used to request further pages, when available. string list_name optional Bytestring name of the list. As specified in the request. string list_size optional Number of items requested for the complete ranked list. This is not a guaranteed count of eligible items. integer offset optional 1-based rank of the first item in this page, returned by the /lists endpoint. integer Recommendations Name Description Schema device_id optional Unique identifier for an unregistered user (e.g. cookie). Use the value "no-consent" for users that wish to remain anonymous. string lists optional List of lists of items < ResponseList > array request_id optional The request identifier as supplied by Froomle. This request_id needs to be supplied with each logged event. string user_group optional The group the user is assigned to. If users get the Froomle experience, this will always be "froomle". string user_id optional the user id of the logged-in user string