> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conductor.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Learn how to efficiently retrieve large datasets in API v2 from QuickBooks Desktop using cursor-based pagination.

Conductor's QuickBooks Desktop API v2 uses cursor-based pagination to handle large datasets efficiently, allowing you to retrieve results in manageable chunks. This guide explains how to implement pagination and its key limitations.

## How pagination works

For list endpoints that support pagination (indicated by the presence of a `cursor` query parameter in the API specification), the process works as follows:

1. Make your initial request to the list endpoint without a cursor.
   * Use the `limit` query parameter to control how many items are returned per page.
     * The default and maximum value is `150` items per page. We enforce this limit to prevent overloading QuickBooks Desktop.

2. The response will contain the following pagination fields:
   * `nextCursor` - The cursor value to use when requesting the next page of results. This field is `null` if there are no more pages.
   * `hasMore` - Indicates whether there are more pages of results available.
   * `remainingCount` - The number of remaining items that can be retrieved in subsequent pages.

3. To fetch the next page, make another request with the `cursor` query parameter set to the `nextCursor` value from the previous response.

   <Warning>
     **You must make subsequent pagination requests within 10 seconds of
     receiving the previous response.** If you exceed this time limit, you'll
     receive an error.
   </Warning>

   * This limitation is inherent to QuickBooks Desktop's design. - While this is
     not an issue when using code to automatically fetch pages in sequence (e.g.,
     in a loop), it may affect manual API testing where you're copying and pasting
     cursor values between requests.

4. Repeat until `hasMore` is `false`.

5. Attempting to request another page when `hasMore` is `false` will result in an error.

## Important limitations

### Same `cursor` value used for all pages

The `cursor` value remains constant throughout the entire pagination sequence. This means you should reuse the same cursor value for all subsequent requests in the sequence, which is a design characteristic inherent to the QuickBooks Desktop system.

### No custom sorting available

The order of results is determined entirely by QuickBooks Desktop, and no information about the ordering is provided in the response. Due to this limitation, custom sorting of results is not supported through the API.

### Non-paginated endpoints

Some QuickBooks Desktop list APIs do not support pagination due to limitations in QuickBooks Desktop itself. These endpoints can be identified by the absence of the `cursor` parameter in their API specification. This typically applies to endpoints where the end-user is highly unlikely to have a large set of objects of that type, so the absence of pagination will not impact performance.

## Pagination in Conductor SDKs

Our official client libraries handle pagination automatically, making it easier to work with paginated responses. Check out their documentation for implementation details:

* [Node.js SDK](https://github.com/conductor-is/quickbooks-desktop-node?tab=readme-ov-file#auto-pagination)
* [Python SDK](https://github.com/conductor-is/quickbooks-desktop-python?tab=readme-ov-file#pagination)

## Example

1. Initial request:

   ```http  theme={"system"}
   GET https://api.conductor.is/v1/quickbooks_desktop/customers
   ```

   ```json Example initial response theme={"system"}
   {
     "data": [...],
     "nextCursor": "abc123",
     "hasMore": true,
     "remainingCount": 99
   }
   ```

2. Next page request with `cursor` query parameter:

   ```http  theme={"system"}
   GET https://api.conductor.is/v1/quickbooks_desktop/customers?cursor=abc123
   ```

   ```json Example next page response theme={"system"}
   {
     "data": [...],
     "nextCursor": "abc123",
     "hasMore": false,
     "remainingCount": 0
   }
   ```

3. Requesting another page after `hasMore` is `false` will result in an error:

   ```http  theme={"system"}
   GET https://api.conductor.is/v1/quickbooks_desktop/customers?cursor=abc123
   ```

   ```json Example error response theme={"system"}
   {
     "error": {
       "message": "No more results available"
       // ...
     }
   }
   ```


Built with [Mintlify](https://mintlify.com).