Paginated collections

Pagination gives you the ability to limit the size of the returned data and to retrieve a specified subset of a large data set.

To reduce load on the service, retrieve operations return a maximum limit of 200 items at a time. If a request supplies no limit or one that exceeds the configured default limit, the default limit of 25 items is used instead.

Pagination has two key concepts: limit and marker.

  • Limit is the restriction on the maximum number of items for that type that can be returned.
  • Marker is an index value. The index value has a minimum value of zero, and a maximum value that does not exceed the number of items in the resource list. For example, if the resource is a billing summary, the marker is the item index of the billing summary result at which to begin the list of the paged results.

To navigate the collection, you can set the limit and marker parameters in the URI. For example, ?limit=10&marker=1234 displays a maximum of 10 items of the billing summary in the paginated results, beginning with the item whose index is 1234 in the returned result list.

If a marker beyond the end of a list is given, an empty list is returned.