User Guides
Using the Public API

Paginating the API Requests

10min

Pagination is a common technique used in APIs to manage large datasets by splitting them into smaller, manageable chunks or pages. This user guide explains how to use pagination with the API query parameters provided, including limit, offset, order, and dir.

In the following examples the endpoint /api/resource/ is used to explain the usage of pagination parameters, but this endpoint is not available. Please see the API documentation for endpoints supporting these parameters e.g "Get the organisations for which the current user is a member".

Pagination parameters

1. limit

  • Description: The limit parameter specifies the maximum number of entries to return in a single API response.
  • Data Type: number
  • Default: 1000

Example:

GET /api/resource?limit=10

In this example, the API will return a maximum of 10 entries in the response.

2. offset

  • Description: The offset parameter determines the starting point within the list of entries from which results will be returned.
  • Data Type: number
  • Default: 0

Example:

GET /api/resource?offset=20

In this example, the API will skip the first 20 entries and return results starting from the 21st entry.

3. order

  • Description: The order parameter allows you to specify the column by which you want to order the results. For example, you can order by the created or updated column. Check the API specification for options.
  • Data Type: string
  • Example Allowed Values: created, updated
  • Default: created

Example:

GET /api/resource?order=created

In this example, the API will order the results based on the created column.

4. dir

  • Description: The dir parameter lets you specify the sort direction for ordered results. You can choose either ascending (asc) or descending (desc) order.
  • Data Type: string
  • Allowed Values: asc, desc
  • Default: asc

Example:

GET /api/resource?order=updated&dir=desc

In this example, the API will order the results by the updated column in descending order.

Combining Pagination Parameters

You can combine these pagination parameters to fine-tune your API requests. Here's an example that demonstrates how to use all the parameters together:

GET /api/resource?limit=20&offset=40&order=created&dir=asc

In this example:

  • limit=20
    specifies that you want a maximum of 20 entries per page.
  • offset=40
    skips the first 40 entries, starting from the 41st entry.
  • order=created
  • dir=asc
    sorts the results in ascending order.

Getting all the results

To get all the data from a paginated API endpoint you need to loop until the number of returned items is less that the limit asked for. For example:

JS
Go