Pagination

The list endpoints that can return many rows answer one page at a time. The endpoint pages mark them: their query parameters include Page and PageSize, and their response body is a PaginatedList.

Request

Name	Type	Default	Description
Page	number	None	The page to read, counting from 1. The name is matched without regard to case, so page works too. On most lists a value below 1 is refused with a validation error.
PageSize	number	None	How many items one page holds. The largest size depends on the list: 100 on an ordinary list, 200 on a report. On most lists a size outside 1 to the largest is refused.

Pass them in the query string. This reads the second page of 25 clients:

GET /api/clients?Page=2&PageSize=25

ℹ

The request names are Page and PageSize, but the response calls the page pageNumber. A request with a pageNumber parameter does not read that page: the name is not recognised, so the call is treated as if no page was given.

Out-of-range values are refused, not adjusted, on most lists. Asking GET /api/clients?Page=0&PageSize=500 answers 400 with VALIDATION_ERROR:

{
  "type": "VALIDATION_ERROR",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "page": ["Page must be 1 or greater."],
    "pageSize": ["Page size must be between 1 and 100."]
  }
}

A few lists, among them the list of users, adjust the values instead: a size above the largest is cut to it and a page below 1 is read as 1. The endpoint page does not say which kind a list is, so check the values you got back in the response.

A page after the last is not an error: it answers 200 with an empty items list.

Response

A paginated endpoint answers with a PaginatedList:

Name	Type	Default	Description
items	array	None	The items on this page.
pageNumber	number	None	The number of this page, counting from 1.
pageSize	number	None	The page size that was applied.
totalPages	number	None	How many pages the whole result has.
totalCount	number	None	How many items the whole result has.
hasPreviousPage	boolean	None	True when pageNumber is greater than 1.
hasNextPage	boolean	None	True when pageNumber is less than totalPages.
metadata	object or null	None	Extra data about the list as a whole, for the endpoints that have some. Null otherwise.

{
  "items": [
    { "id": 8, "email": "customer5@example.test" },
    { "id": 7, "email": "customer4@example.test" }
  ],
  "pageNumber": 1,
  "pageSize": 2,
  "totalPages": 10,
  "totalCount": 20,
  "hasPreviousPage": false,
  "hasNextPage": true,
  "metadata": null
}

To read every page, follow hasNextPage until it is false.

Some list endpoints return a plain array and no paging at all, for example the invoices of a client. Their endpoint page shows the array as the body.