# Pagination

Many endpoints that return top-level collections of data allow for pagination of returned items. The requested page specification must be formatted as a dictionary within the page parameter.

Pagination values provided in a request that cannot be coerced or that exceed specified ranges result in a 400 Bad Request response.

Pagination values that request ranges not available (for example, requesting page 4 when there is only enough data for 3 pages) will respond with an empty dataset and pagination metadata showing that the requested page is out of range.

## Page Number

Page number can be provided as `page.number` and defaults to 1 (page). The page size defaults to 100 records per page.

**Examples**

`GET /v2/content?page.size=50&page`

* This retrieves 50 records per page.


`GET /v2/content?page.size=50&page.number=2`

* This retrieves 50 records per page but starts from page 2 as set by `page.size` (i.e., skipping the first 50 records).


## Page Size

Page size can be provided as `page.size`. Each endpoint specifies its own default page size outside of the default 10, maximum 100.

**Example**

`GET /v2/content?page.size=10`

* This request retrieves 10 records starting from the first page.


## Total Records

When using page-based pagination, most endpoints return a `total_records` field in the response:


```
{
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_records": 73
  }
}
```

Use this to determine how many times to paginate. The example above would need 8 pages.

## Start Index

For large result sets, you can use the `startIndex` query parameter to control pagination. `startIndex` is 1-based, meaning it specifies the position of the first record to return.

**Example**

`GET /scim/v2/Users?startIndex=10`

* `startIndex=10` skips the first 9 records.


### Count

You can use the `count` query parameter to limit the number of records returned.

**Example**

`count=10` only returns 10 records from a list with a greater number of possible records to return.

Using both `startIndex` and `count` query parameters in a `GET` users request looks like:

`GET /scim/v2/Users?startIndex=20&count=10`

This example returns 10 users starting from the 20th user in the list.

## Page Cursor

Webhooks use cursor-based pagination. Instead of numeric page indices, these endpoints return a cursor token in the `meta.pagination` object:


```
"meta": {
  "pagination": {
    "cursor": "abc123",
    "next": "def456",
    "page_size": 25
  }
}
```

Webhooks Overview
Browse our overview documentation that describes how our webhooks work.

Webhooks Endpoints
Browse our available Webhooks endpoints.

## Sorting

Only some endpoints provide the ability to sort the returned records. Usually these are endpoints that list records, such as:

* [Listing channels (topics)](/doorman/openapi/content-publishing/listchannels).
* [Listing users](/doorman/openapi/user-management/listusers).


If sorting is supported, the endpoint will use a `?sort=` query parameter to specify the sort field. The available sort parameters will be documented for each specific endpoint.

**Examples**

* `?sort=title` — sorts by title in ascending order (default).
* `?sort=-title` — sorts by title in descending order (e.g., "Zoo" before "Animal").


You can also provide multiple sort criteria, separated by commas:


```

?sort=title,created_at
```

This sorts by `title`, and for records with the same title, it further sorts by `created_at`.

Attempting to sort using a parameter not supported by the endpoint will typically result in a 400 Bad Request error. Check each endpoint's reference documentation.