# GET /{environment}/recommendations/lists

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/lists_with_env.html)

<a id="_description"></a>

## 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.

<a id="_parameters"></a>

## Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which a request is made. | string |
| **Query** | **limit**<br>_required_ | Maximum number of items to return, starting at `offset`. | integer |
| **Query** | **list\_key**<br>_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**<br>_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 |

<a id="_responses"></a>

## Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [Recommendations](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/lists_with_env.html#_recommendations) |
| **404** | list\_key not found, it either expired or never existed | No Content |

<a id="_produces"></a>

## Produces

-   `application/json`
    

<a id="_tags"></a>

## Tags

-   recommendations
    

<a id="_example_http_response"></a>

## Example HTTP response

<a id="_response_200"></a>

### Response 200

```json
{
  "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"
}
```

* * *

<a id="_item"></a>

### Item

One content-item.

| Name | Description | Schema |
| --- | --- | --- |
| **information\_field**<br>_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**<br>_required_ | The identifier of the recommended item | string |
| **rank**<br>_required_ | The item’s position in the complete ranked list. The first item has rank 1. | integer |

<a id="_responselist"></a>

### 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**<br>_optional_ | Items returned for this page, up to the requested `limit`. Fewer items may be returned when fewer eligible recommendations are available. | < [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/lists_with_env.html#_item) > array |
| **limit**<br>_optional_ | Maximum number of items requested for this page, not the number actually returned. | integer |
| **list\_key**<br>_optional_ | Opaque identifier used to request further pages, when available. | string |
| **list\_name**<br>_optional_ | Bytestring name of the list. As specified in the request. | string |
| **list\_size**<br>_optional_ | Number of items requested for the complete ranked list. This is not a guaranteed count of eligible items. | integer |
| **offset**<br>_optional_ | 1-based rank of the first item in this page, returned by the /lists endpoint. | integer |

<a id="_recommendations"></a>

### Recommendations

| Name | Description | Schema |
| --- | --- | --- |
| **device\_id**<br>_optional_ | Unique identifier for an unregistered user (e.g. cookie). Use the value `"no-consent"` for users that wish to remain anonymous. | string |
| **lists**<br>_optional_ | List of lists of items | < [ResponseList](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/lists_with_env.html#_responselist) > array |
| **request\_id**<br>_optional_ | The request identifier as supplied by Froomle. This request\_id needs to be supplied with each logged event. | string |
| **user\_group**<br>_optional_ | The group the user is assigned to. If users get the Froomle experience, this will always be "froomle". | string |
| **user\_id**<br>_optional_ | the user id of the logged-in user | string |