> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

Pagination enables you to control the volume of the responses returned by Storefront Gateway APIs, and to render those responses in ordered segments (or pages).

Storefront Gateway includes a variety of APIs that can return multiple results. For instance, `GET user/{userId}/features` returns all Features associated to the given User ID. Since Storefront Gateway's data model supports many-to-many associations between entities, any one entity can grow to have a significantly large number of associations.

A high number of results within a single response can put a strain on the system or the UI retrieving and rendering those entities. To control the number of results in a given call, a select number of Storefront Gateway APIs support pagination to break up large results into easily renderable pages.

## Pagination Parameters

The optional `size` and `offset` request parameters enable the fetching of data in smaller, manageable segments:

| Name | Type | Required? | Description | Default | Notes |
| - | - | - | - | - | - |
| `size` | request parameter (num) | No | Indicates the maximum number of entities to be included in a single-page response. | 20 | Maximum size is 100. Cannot be a negative value. |
| `offset` | request parameter (num) | No | Indicates the number of results to skip in a response. For example, an offset of 20 means that the response skips the first 20 results (and thus starts at 21). | 0 | Cannot be a negative value. |

A request that exceeds the maximum size or has a negative offset, results in an HTTP 400 (BAD REQUEST) response.

**Note:** An internal application setting controls the default and maximum size values. Reach out to your product team contact if you would like to modify these values.

## Pagination Header

Successful responses from Storefront Gateway include an `X-Total-Count` header that indicates the total number of available entities.

| Name | Type | Description |
| - | - | - |
| X-Total-Count | Response header | Any successful request (HTTP 200 OK) must respond with the response header `X-Total-Count` set to the available number of entities. |

## Multiple Page Response

Here is a simple pagination example where there is a total count of 4 results broken up into two pages.

```
**GET REQUEST - Page 1**
GET /membership/1/subscriptions?offset=0&size=2
```

```
**GET RESPONSE - Page 1**
Header: X-Total-Count = 4
[
   {
      "id": 1,
      "displayName": "Cable TV"
   },
   {
      "id": 2,
      "displayName": "Video on Demand"
   }
]
```

```
**GET REQUEST - Page 2**
GET /membership/1/subscriptions?offest=2&size=2
```

```
**GET RESPONSE - Page 2**
Header: X-Total-Count = 4
[
   {
      "id": 3,
      "displayName": "HBO"
   },
   {
      "id": 4,
      "displayName": "Netflix"
   }
]
```

## Zero "size" value

A request size of zero will retrieve **all** results if the total number of results is *less than* the max page size. For example, assume that there are 3 available results, and that the internal max page size setting is set to 5.

```
**REQUEST**
GET /membership/1/subscriptions?size=0
```

```
**RESPONSE**
Header: X-Total-Count = 3
[
   {
      "id": 101,
      "displayName": "Gaming Streaming Service"
   },
   {
      "id": 2,
      "displayName": "Music Streaming Service"
   },
   {
      "id": 3,
      "displayName": "Movie Streaming Service"
   }
]
```

A request size of zero returns an error response if the total number of results *exceeds* max page size. For example, assume that there are 10 available results, and that the internal max page size setting is set to 5.

```
**REQUEST**
GET /membership/1/subscriptions?offset=0&size=0
```

```
**RESPONSE**
{
   "operationError": {
      "code": "max-return-page-size",
      "message": "The total number of results exceeds the maximum page size"
   }
}
```

## Exceeding max size

A request with a size value that exceeds the maximum page size returns an error response. For example, in the call below, assume that the internal max page size setting is set to 20.

```
**REQUEST**
GET /membership/1/subscriptions?offest=0&size=20
```

```
**RESPONSE**
{
   "operationError": {
      "code": "page-size-error",
      "message": "The requested page size is bigger than allowed maximum size"
   }
}
```

## API Listing

The following user management GET calls support pagination parameters, and return an `X-Total-Count` header:

| `user/runtimes` | `/user/{userId}/runtimes` | `/user/features` |
| - | - | - |
| `/user/{userId}features` | `/user/subscriptions` | `/user/{userId}/subscriptions` |
| `/user/groups` | `/user/{userId}/groups` | `/user/accounts` |
| `/user/{userId}/accounts` | `/group/{groupId}/users` | `/group/{groupId}/accounts` |
| `/group/{groupId}/subscriptions` | `/group/{groupId}/runtimes` | `/group/{groupId}/features` |
| `/account/{accountId}/users` | `/account/{accountId}/groups` | `/account/{accountId}/runtimes` |
| `/account/{accountId}/subscriptions` | `/subscription/{subscriptionId}/users` | `/subscription/{subscriptionId}/groups` |
| `/subscription/{subscriptionId}/features` | `/subscription/{subscriptionId}/runtimes` | `/feature/{featureId}/groups` |
| `/feature/{featureId}/runtimes` | `/feature/{featureId}/users` | `/runtime/{runtimeId}/groups` |
| `/runtime/{runtimeId}/accounts` | `/runtime/{runtimeId}/subscriptions` | `/runtime/{runtimeId}/features` |
| Other Storefront Gateway APIs, such as our Custom Data APIs, can support pagination as well. | | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.