Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Paging Syntax

 

To limit the results returned in an API retrieval request, HTTP GET, most JSA API endpoints that return lists of resources support the Range header parameter.

The Range parameter syntax is consistent for all endpoints that support it. Refer to the documentation for the endpoint to determine whether the Range parameter applies to it. Any limitations on the Range syntax are included in that endpoint's description.

Note

The Range parameter is always sent as a header parameter, unlike the sort, filter, and fields parameters. These parameters are typically query parameters.

By default, only the first 50 records are returned for the Range parameter on the interactive API documentation page. You can alter the Range value for an endpoint. However, if you request large result sets, it might negatively affect the performance of the interactive API documentation page.

Range Header Parameter

Paging requests are specified with the Range header parameter. Use the following zero-indexed syntax:

Range: items=x-y

The response to a request that employs paging includes the Content-Range header. The header indicates the number of records that were returned within the content range in the following format:

Content-Range: items x-y/total number of records received

For example, to return the first 5 records, the request header contains the following parameter:

"Range: items= 0-4"

The response header for that request returns the following information:

Content-Range: items 0-4/5

If the requested range exceeds the number of records, all records that are within the stated range are returned. In the following example, the first 100 records are requested:

“Range: items= 0-99”

However, there are only 12 records in total. The response returns all records within the stated range:

Content-Range: items 0-11/12

If the range requested is beyond the bounds of the amount of records, then no records are returned. In the following example, the first records 3 to 5 records are requested:

“Range: items = 3-5”

However, there are fewer than 3 records, and so no records are returned:

Content-Range: items */3