Pagination
Paginate through large result sets
List endpoints return one page of results at a time, using offset-based
pagination. The default page size is 50 records. Most endpoints accept a
page[limit] of up to 500 and return a 422 error above that. Each endpoint's
API reference lists its maximum.
Request
Control the page with the page[limit] and page[offset] parameters:
curl --globoff \
-H "Authorization: api-key YOUR_API_KEY" \
"https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page[limit]=100&page[offset]=200"| Parameter | Type | Default | Description |
|---|---|---|---|
page[limit] | integer | 50 | Records per page (max 500 on most endpoints) |
page[offset] | integer | 0 | Number of records to skip before the current page |
Response
The response includes pagination metadata and navigation links:
{
"data": [...],
"meta": {
"total_records": 1250,
"total_pages": 13,
"offset": 200,
"limit": 100
},
"links": {
"next": "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page%5Blimit%5D=100&page%5Boffset%5D=300",
"prev": "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page%5Blimit%5D=100&page%5Boffset%5D=100"
}
}Both links keys are always present. next is null on the last page, and
prev is null on the first page.
Link URLs are percent-encoded, so they are safe to fetch verbatim — including
any filter values that contain &, #, or spaces. Pass them through unchanged
rather than rebuilding them.
| Field | Description |
|---|---|
meta.total_records | Total matching records across all pages |
meta.total_pages | Total number of pages |
meta.offset | Offset of the current page |
meta.limit | Current page size |
links.next | URL for the next page, or null on the last page |
links.prev | URL for the previous page, or null on the first |
Fetching all pages
Follow the links.next URL until it's null:
async function fetchAll(workspace, object, apiKey) {
const records = [];
let url = `https://api.clarify.ai/v1/workspaces/${workspace}/objects/${object}/resources?page[limit]=100`;
while (url) {
const res = await fetch(url, {
headers: { Authorization: `api-key ${apiKey}` },
});
const json = await res.json();
records.push(...json.data);
url = json.links?.next;
}
return records;
}Ordering
Sort results with the sortOrder parameter:
curl --globoff \
-H "Authorization: api-key YOUR_API_KEY" \
"https://api.clarify.ai/v1/workspaces/acme/objects/deal/resources?sortOrder[column]=amount&sortOrder[dir]=DESC"| Parameter | Description |
|---|---|
sortOrder[column] | Field name to sort by |
sortOrder[dir] | ASC or DESC |
On the /resources endpoints, results without sortOrder come back ordered by
_id. With sortOrder, records that share a sort value are ordered by _id.
Page boundaries stay fixed while the data is unchanged. Records created,
deleted, or updated between requests can still shift across pages.
See Filtering for narrowing results before you page through them.