Using Pagination

The Connect API utilises cursor-based pagination to efficiently retrieve large sets of data. Cursor-based pagination provides "next" and "previous" cursors in the API response, allowing you to navigate through the dataset effectively.

In addition to cursor-based pagination, our API also supports basic offset pagination using the limit and offset fields. This method allows you to fetch data by specifying the number of items you want per page (limit) and the starting index of the data (offset) in the dataset.

When making an API request to and endpoint that is paginated it will respond with a data array that includes the results and a pagination object tat contains the pagination metadata:

  • total: The total number of results

  • limit: The limit specified for the current request, if no limit was specified this will use the endpoint default.

  • offset: The offset specified for the current request, this will be 0 when using cursors

  • previousCursor: A cursor that represents the previous page of data. If there is no previous page, this field will be set to null.

  • nextCursor: A cursor that represents the next page of data. If there is no next page, this field will be set to null.

Cursor Pagination

Cursor-based pagination is a method that uses unique identifiers (cursors) to mark the position in the dataset. These cursors help you fetch the next or previous page of data as needed. Each cursor points to a specific record in the result set.

Requesting the Next Page

To request the next page of data, you should include the nextCursor value from the previous response in your subsequent API request. The API will use this cursor to determine where to start fetching the next set of results. If the nextCursor is not provided or is null, it means you have reached the end of the dataset, and there are no more records to fetch.

Requesting the Previous Page

To request the previous page of data, you should include the previousCursor value from the previous response in your subsequent API request. The API will use this cursor to determine where to start fetching the previous set of results. If the previousCursor is not provided or is null, it means you are already at the first page of the dataset, and there are no previous records to fetch.

Example API Response 

{
  "data": [
    {
      "id": "123",
      "name": "Item 1",
      "description": "This is item 1"
    },
    {
      "id": "456",
      "name": "Item 2",
      "description": "This is item 2"
    }
    // Additional items in the current page...
  ],
  "pagination": {
    "total": 300,
    "limit": 20,
    "offset": 0,
    "nextCursor": "dXNlcjEwMDA=",
    "previousCursor": "dXNlcjEwMjQ="
  }
}

Example next page request 

GET /api/data?cursor=dXNlcjEwMjQ=

Offset Pagination

When making an API request for data using offset pagination, you will include the limit and offset parameters in your query. The API will use these parameters to determine how many records to return (limit) and from which position in the dataset to start fetching the data (offset).

Requesting Data with Offset Pagination

To request data using basic offset pagination, include the following parameters in your API request:

  • limit: The number of items to return per page. This value must be a integer, representing the maximum number of records to include in the response.

  • offset: The starting index of the data in the dataset. This value must be a integer, indicating the position of the first record you want to retrieve.

Example API Request 

GET /api/data?limit=10&offset=20

This API request will fetch 10 records from the dataset, starting from the 21st record (zero-based index).