The Ad Manager API provides collections of data, most commonly in `List`
methods. Collections can be arbitrarily sized and are paginated in API
responses.

### Basics

Request messages for collections define an optional integer `pageSize` field to
specify the maximum number of results to return.

Set the `pageSize` parameter to a positive number, less than `1000`. If you
don't set any value or set the parameter to zero, the API uses a default value
of `50`. If you set the parameter to a negative value, the API returns an
`INVALID_ARGUMENT` error.

Refer to the resource reference documentation, for example
[`AdBreaks`](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.liveStreamEventsByAssetKey.adBreaks/list#query-parameters),
for a resource specific `pageSize` value.

The API might return fewer results than the number requested (including zero
results), even if not at the end of the collection. Use the presence of the
`nextPageToken` field to determine if there are additional results in the
collection.

Response messages for collections define a string `nextPageToken` field, which
can be used to retrieve the next page. The `nextPageToken` field is empty when
the end of the collection is reached. This is the only way to determine if you
have reached the end of a collection.

Request messages for collections define an optional string `pageToken` field to
advance to the next page in the collection. Changes to the `pageSize` in a
request for subsequent pages are allowed. All other arguments must be the same;
if any arguments are different, the API returns an `INVALID_ARGUMENT` error.

#### Example

### cURL

Initial request

    curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500

    {
      "adUnits": [ ... ],
      "nextPageToken": "eCGwAcs6hUerggzd2DGv"
    }

Next page request

    curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv

    {
      "adUnits": [ ... ]
    }

### Total size

Response messages for collections provide an integer `totalSize` that represents
the total number of entities after filtering is applied. This field is only
populated when requested in the [field mask](https://developers.google.com/ad-manager/api/beta/field-masks).

    GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize

### Order results

Request messages for collections define a string `orderBy` field to specify
sorting order.

Values should be a comma separated list of fields. For example: `foo,bar`. The
default sorting order is ascending. To specify descending order for a field,
append a `desc` suffix; for example: `foo desc, bar`. Redundant space
characters in the syntax are ignored. The `orderBy` values `foo, bar desc`, `foo , bar desc`, and `foo,bar desc` are all equivalent. Subfields are specified
with a `.` character, such as `foo.bar` or `address.street`.

Ordering is only supported on primitive fields.

### Skip results

Methods for a paginated operation define an integer `skip` field to skip
results. The skip value refers to the number of individual resources to skip,
not the number of pages.

For example:

A request with no page token and a skip value of 30 returns a single page of
results starting with the 31st result.

A request with a page token corresponding to the 51st result (because the first
50 results were returned on the first page) and a skip value of 30 returns a
single page of results starting with the 81st result.

If a skip value is provided that causes the cursor to move past the end of the
collection of results, the response is `200 OK` with an empty result set with no
`nextPageToken`.

> [!IMPORTANT]
> **Important:** The `skip` field should **not** be used as a substitute for pagination. The pagination token ensures the response is from the same initial result set.