Paging

The REST API service limits the number of resources returned by a single request.

To retrieve more results, multiple requests must be submitted (pagination). When more entries exist than the response holds, the response contains an @odata.nextLink with the URL of the next page. Treat that URL as opaque: request it as it is, without adding query options.

Without $top, a response holds at most 20 entries. When more exist, @odata.nextLink points to the next 20:

GET http://myserver:5181/odata/ServiceRequests

"@odata.nextLink": "http://myserver:5181/odata/ServiceRequests?$skip=20"

With $top=n, the request returns at most n entries in total, as OData 4.0 defines. A request for 50 entries returns 50 entries and no next link:

GET http://myserver:5181/odata/ServiceRequests?$top=50

No response holds more than 250 entries. When $top asks for more, the response holds the first 250, and @odata.nextLink asks for the rest:

GET http://myserver:5181/odata/ServiceRequests?$top=300

"@odata.nextLink": "http://myserver:5181/odata/ServiceRequests?$top=50&$skip=250"

In detail, $top and the paging around it work as follows:

$top=n limits the total number of entries across all pages to n. The last page has no @odata.nextLink, also when the collection holds more entries.
A response holds at most 250 entries. Each next link carries the number of entries still to be returned in $top, and moves $skip on by one page.
$top=0 returns an empty collection.
$skip is applied before $top. Each next link carries the request’s other query options.
When the data runs out, the response has no @odata.nextLink.
$count=true returns the number of entries that match $filter across all pages, whatever $top and $skip say. Next links repeat it.
Without $orderby, entries are ordered by their key (Uid), so pages do not overlap or skip entries. With $orderby, the key is added as the last sort criterion.
The same rules apply to a collection reached by navigation.

Choosing the Page Size

To read a collection in pages of a size you choose, send the odata.maxpagesize preference in a Prefer header instead of $top. The service then returns at most that many entries per response, up to 250, and confirms the preference in a Preference-Applied header. Send the same header with each next link.

GET http://myserver:5181/odata/ServiceRequests
Prefer: odata.maxpagesize=100

Preference-Applied: odata.maxpagesize=100
"@odata.nextLink": "http://myserver:5181/odata/ServiceRequests?$skip=100"

A value above 250 is answered with pages of 250 and Preference-Applied: odata.maxpagesize=250. A value that is not a positive whole number is ignored. Combined with $top, odata.maxpagesize sets the page size and $top the total.

Changed in revision 2.5

Before revision 2.5 of this guide, $top set the page size: next links continued in pages of n through the whole collection, $top had no upper limit, and $top=0 returned 20 entries. A client that reads every page with $top and the next link now stops after n entries. To keep reading the whole collection, drop $top, or use odata.maxpagesize to choose the page size.

Query Options for Paging

Query Option	Description
`$skip=n`	Skips the first `n` records.
`$top=n`	Returns at most `n` records in total. Pages hold at most 250 records; the next link returns the rest.
`$count=true`	Includes the total number of entries in the response.

Preference	Description
`Prefer: odata.maxpagesize=n`	Sets the page size to at most `n`. Default: 20. Maximum: 250.

Example Usage

Retrieve the first 50 results:

GET http://myserver:5181/odata/ServiceRequests?$top=50

Retrieve results 21–40:

GET http://myserver:5181/odata/ServiceRequests?$skip=20&$top=20

Retrieve results and include a total count:

GET http://myserver:5181/odata/ServiceRequests?$count=true

Read the whole collection in pages of 100:

GET http://myserver:5181/odata/ServiceRequests
Prefer: odata.maxpagesize=100