Box Developer Documentation
Log in

Offset-based Pagination

Guides API Calls Pagination Offset-based Pagination
Edit this page

Offset-based Pagination

APIs that use offset-based paging use the offset and limit query parameters to paginate through items in a collection.

Offset-based pagination is often used where the list of items is of a fixed and predetermined length.

Paging

To fetch the first page of entries in a collection the API needs to be called either without the offset parameter, or with the offset set to 0. The limit field is optional.

curl https://api.box.com/2.0/folders/0/items?offset=0&limit=100 \
    -H "authorization: Bearer ACCESS_TOKEN"

To fetch the next page of entries the API needs to be called with an offset parameter that equals the sum of the previous offset value and limit returned in the previous result, previous_offset + previous_limit.

curl https://api.box.com/2.0/folders/0/items?offset=100&limit=100 \
    -H "authorization: Bearer ACCESS_TOKEN"

Note that the offset should be increased by the previous limit and not by the size of the entries in the response array, as this may be less than the limit. Generally we advise using the value of the limit in the response object to increase the offset value.

The final page of items has been requested when the next offset value exceeds the total_count value in the response object. At this point there are no more items to fetch.

Offset & Limit

The following query parameters are used to paginate a collection.

Query parameterTypeDefault
offsetInteger0The (zero-based) offset of the first item returned in the collection. In a zero-based offset 0 is a correct value.
limitIntegerDepends on APIThe maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

The maximum offset for offset-based pagination is 9999. Marker-based pagination is recommended when a higher offset is needed.

Collections

When paginating collections, the API returns an object that contains the set of results as an array, as well as some information about the current page of results.

FieldType
entriesArrayThe page of items for this page. This will be an empty array if there are no results.
offsetIntegerThe offset used for this page of results
limitIntegerThe limit used for this page of results. This will be the same as the limit query parameter unless it exceeded the maximum value allowed for this API endpoint.
total_countIntegerOne greater than the offset of the last item in the entire collection. The total number of items in the collection may be less than total_count.

Example endpoints

Some endpoints that support offset-based pagination are: