> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ulm.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 Digital Identity Management APIs, and to render those responses in ordered segments (or pages).

Digital Identity Management 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 Digital Identity Management'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 Digital Identity Management 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 Digital Identity Management 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 Digital Identity Management 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.