This is a staging build of the docs. Do not share the link externally.
Skip to main content

Pagination

Basics and examples of pagination in Codat's APIs

The Codat API uses a simple set of query parameters on most of its endpoints to facilitate paging through large amounts of data.

Request

Our endpoints which return multiple results are paged, e.g. GET /companies. If you're calling these endpoints, you will need to supply a page query parameter. You can configure the size of each page by using the pageSize query parameter.

A typical request will have the following properties:

  • page : This is the page number that you would like to have displayed. The default page is 1.
  • pageSize : You can define the number of results you would like returned per page. The default page size is 100, while the maximum page size can be set to 5000. We recommend using the default page size to ensure optimal response times. Read more on Optimizing API Calls.

Response

A typical response will have the following properties:

  • results: An array of the specified resources
  • pageNumber: Current page number
  • pageSize: Specified number of results
  • totalResults: Total number of records in the result set
  • _links: Links (each with an href field) to help you navigate through the list of results:
    • self: The base resource your request was sent to, without any query parameters
    • current: Link to the current URL, including any query parameters
    • next: Link to the next page, including any query parameters
    • previous: Link to the previous page, including any query parameters

You can use the totalResults and pageSize to calculate the number of pages that will be required to retrieve all of the available data.

You're not required to set the page query parameter manually. If you want to navigate through the pages, you can use the _links property.

Note: totalResults returns the number of results after applying any filter you've specified using the query parameter. For example: if there are 100 invoices in total, with 50 of them being paid, then calling the invoices endpoint with the query status=paid would return "totalResults": 50 rather than "totalResults": 100.

Example

using CodatPlatform;
using CodatPlatform.Models.Shared;
using CodatPlatform.Models.Operations;

var codatPlatform = new CodatPlatformSDK(
security: new Security() {
AuthHeader = "Basic BASE_64_ENCODED(API_KEY)",
}
);

var res = await codatPlatform.Companies.ListAsync(new ListCompaniesRequest() {
Page = 5,
PageSize = 20,
});

// handle response
GET /companies/{companyId}/data/invoices?page=5&pageSize=20
Sample response
{
"results": ["...":"..."],
"pageNumber": 5,
"pageSize": 20,
"totalResults": 90,
"_links": {
"current": {
"href": "/companies?page=5&pageSize=20"
},
"self": {
"href": "/companies"
},
"previous": {
"href": "/companies?page=4&pageSize=20"
}
}
}
Recap

You have learned:

  • How to paginate with the page and pageSize parameters


Was this page useful?
❤️
👍
🤔
👎
😭