Pagination
List endpoints return a page of rows, not an unbounded collection. The exact filters and sortable fields are documented on each endpoint, while this page explains the shared paging model.
Request parameters
Use page to choose the page number and limit to choose the maximum number of rows in that page.
{
"page": 1,
"limit": 20,
"sort_by": "created_at",
"sort_order": "desc"
}
| Field | Meaning |
|---|---|
page | 1-based page number. The first page is 1. |
limit | Maximum rows to return for the page. The API validates this against the endpoint limit. |
sort_by | Field used to order the result set, when the endpoint supports sorting. |
sort_order | asc or desc, when the endpoint supports sorting. |
page must be 1 or greater. limit must be positive and is capped by the endpoint. Public list endpoints commonly cap limit at 500. Use the endpoint schema as the source of truth.
Response metadata
Paged responses place rows in data and paging information in meta.pagination.
{
"message": "OK",
"details": "Orders returned",
"data": [
{
"order_id": "ORD-9001"
}
],
"meta": {
"pagination": {
"page": 1,
"limit": 20,
"total": 52
}
}
}
| Field | Meaning |
|---|---|
meta.pagination.page | Current page number after validation. |
meta.pagination.limit | Page size used for this query. |
meta.pagination.total | Total rows matching the filters before paging. |
The API does not return pages or page_size. Clients can calculate page count with Math.ceil(total / limit) when needed.
Sorting
When sorting is available, sort_by is restricted to fields listed by the endpoint schema. Sending an unsupported field returns a validation or bad-request style response instead of falling back silently.
Prefer a stable sort for repeated polling. For example, use created_at desc to read newest activity first, or row_no asc when reviewing bulk-upload rows in file order.
{
"page": 1,
"limit": 50,
"sort_by": "row_no",
"sort_order": "asc"
}
Empty pages
If no rows match the filters, data is an empty array and meta.pagination.total is 0. This is a successful response, not an error.
{
"message": "OK",
"details": "Orders returned",
"data": [],
"meta": {
"pagination": {
"page": 1,
"limit": 20,
"total": 0
}
}
}