Skip to main content

Pagination

Index actions are limited to 200 results per request unless otherwise specified. Where the number of results exceeds 200 records, Clio's API will paginate the results.

Metadata about paging is returned in the response body:

{
"data": { ... },
"meta": {
"paging": {
"previous": "https://app.clio.com/api/v4/contacts?fields=...",
"next": "https://app.clio.com/api/v4/contacts?fields=..."
}
},
}

The previous and next fields will be URLs that can be used to retrieve the previous and next page of results. If there is no previous or next page, the field will be omitted.

Pagination Approaches

Clio's API supports two approaches to pagination. Each approach can have benefits, depending on the needs of your application and the size of the data set being accessed. For easy reference, the major differences are shown in the table below.

Cursor paginationOffset Pagination
Total Record LimitUnlimited10,000 total records
ParallelizableNoYes
Custom Sort OrderNo - id(asc) onlyYes

Limited Offset Pagination

To use Limited Offset Pagination, you must include the offset query parameter in your request. This specifies the number of records to skip when processing the request.

For example, the following request below will omit records 1 through 10 from the results:

curl "https://app.clio.com/api/v4/activities?fields=id,quantity,price,total&offset=10"

For performance reasons, the offset pagination method is limited to retrieving 10,000 total records (50 pages total). Attempting to retrieve a page over the limit will result in a 422 ArgumentError.

Because offset is a URL parameter, this pagination method is parallelizable – you can make multiple parallel index requests to an endpoint with differing offset values to quickly retrieve larger amounts of records (e.g. to gather the first 600 results, you can make three parallel requests, with offset=0, offset=200, and offset=400).

Unlimited Cursor Pagination

To use Unlimited Cursor Pagination, you must include the order parameter with a value of id(asc) and no offset parameter. For example:

curl "https:app.clio.com/api/v4/activities?fields=id,quantity,price,total&order=id(asc)"

Cursor pagination has no upper limit to the number of records that can be accessed. As a trade-off, requests must be made in serial; the response from the initial pagination request will contain the URL of the next page of requests in the meta{paging{next}} property, which means you must wait for the first page of results to return before requesting the next page.

If you require a custom sort order for your results other than id(asc), the offset pagination method should be used. Each endpoint has its own set of custom sort orders; refer to the API Reference section for each endpoint to view them.