Overview

Select endpoints now support Cursor-based Pagination (also called Keyset Pagination) for efficiently fetching large data sets. This pagination mode is designed for initial bulk data syncs of large resources.

Endpoints that support this feature include a new paginationMode query parameter.

When paginationMode=CURSOR, the API performs cursor-based pagination instead of traditional page-based pagination. This method retrieves result sets based on the position of the last record from the previous response rather than a numeric page offset.

If paginationMode is omitted, the endpoint will default to traditional page-based pagination for backwards compatibility.

Response Metadata

Responses using cursor pagination include a metadata object with cursor-specific fields, such as:

{ "data": [ ... ], "meta": { "limit": 500, "hasMore": true, "nextStartAfter": "00000000-0000-0000-0000-000000000000" } 

Data is ordered in a deterministic way that approximately mirrors the order in which the resources were created. Each response includes a nextStartAfter cursor value that identifies the position of the last record in the current result set. To fetch the next set of results, include that value in your subsequent request:

GET /v2/clients/{clientUuid}/inspections?paginationMode=CURSOR&startAfter={previous "nextStartAfter"}

Each response will also include a hasMore boolean that indicates whether there are additional records to be synced.

Sync Workflow

We recommend the following workflow for large-scale data synchronization:

1. Mark Current Time

   Before starting the sync, record the current timestamp. This will be used to define the time window for catch-up incremental syncs after the bulk sync is performed.

2. Perform Initial Bulk Sync

   Use paginationMode=CURSOR to iterate through all available data efficiently. After fetching the initial set of results, use the nextStartAfter from the previous response to request subsequent results until hasMore is false.

3. Perform Catch-up Incremental Sync

   After completing the bulk sync, perform a traditional page-based incremental sync to capture any records that may have been created or updated during the initial sync process. Use the timestamp recorded above as the starting point for this sync (i.e. updatedSince=step1Timestamp.

4. Continue Ongoing Incremental Syncs

   Continue performing regular incremental syncs using paged-based pagination to retrieve new or updated records since your last sync.