# Pagination

Various APIs provide the ability to query results in a paginated form. These APIs will typically have an optional `nextToken` input property to facilitate pagination. By default, if a limit is not provided, or set as `undefined/nil/null`, the default limit will be 10.

{% hint style="info" %}
When specifying a large number of records in a query, an upper limit of 1MB is enforced on the data retrieved. This limit is applied before any filter is applied to the data. If the 1MB limit is hit, the data will be returned as a page and require using the next token of the result to query the next page of results.
{% endhint %}

The following types support pagination:

* Funding Sources
* Virtual Cards
* Transactions

If intending to use pagination, the first call to an API should not include a `nextToken`, otherwise the result will return an error. When a paginated API call is successful, the output response will contain a `nextToken` property.

When using a query that supports pagination, it is important to always check the `nextToken`. Due to the nature of the data access from the service, it is possible to retrieve a result with no data but potentially have another page of information to retrieve which may contain results

To access the next page of a query API, use the previously returned `nextToken` in the subsequent API call. If a successful response does not return a `nextToken`, or it is set to `undefined/nil/null`, the pagination results have been exhausted and there are no more pages to retrieve.

{% hint style="warning" %}
When using subsequent calls for pagination, ensure that the input information (e.g. `limit`, `filter`) is the same for each call, otherwise unexpected behavior will occur. For example, if the first call uses an input property of `limit = 8`, then each subsequent call must use a `limit` of `8`.
{% endhint %}

## Pagination Example

{% tabs %}
{% tab title="Swift" %}
Below is an example usage of `listFundingSources(withLimit:)` for a user with 4 funding sources:

```swift
do {
   var output = try await client.listFundingSources(withLimit: 2, nextToken: nil)
   /*
    * This result will contain an `items` array of 2 Funding source objects, as
    * well as a non-`nil` `nextToken` which is used in the subsequent call.
    */
   
   output = try await client.listFundingSources(withLimit: 2, nextToken: output?.nextToken)
   /*
    * This result will also contain 2 objects in the `items` array, however the
    * `nextToken` will be `nil`, as there are no more objects for the user to
    * fetch.
    */
} catch {
    // Handle and cleanup after error.
}
```

{% hint style="info" %}
[`DispatchSemaphore`](https://developer.apple.com/documentation/dispatch/dispatchsemaphore) was used for simplifying the demonstration, we strongly recommend using GCD's [`Operation`](https://developer.apple.com/documentation/foundation/operation) for handling asynchronous code.
{% endhint %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sudoplatform.com/guides/virtual-cards/pagination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.