> For the complete documentation index, see [llms.txt](https://developer.tapraise.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.tapraise.com/api/api-overview/pagination.md).

# Pagination

### What is cursor-based pagination

Cursor-based pagination is used for list calls in the REST endpoints that return a large number of items. Where traditional offset-based pagination separates a large list into chunks of x items based upon a possible changing offset, cursor-based pagination uses fixed cursors.

Using a fixed cursor eliminates the possibility of skipping items and supplying the same item in more than one page. It also allows us to cache the response if needed.

For cursor-based pagination, you supply a cursor to use as a start position, and you describe the number of items you want to fetch before or after that cursor, using combinations of the filter parameters: `first`, `after`, `last`, `before`.

#### Paginating forward

* `?first=10` → returns the first 10 results of the complete result set
* `?first=10&after=c4f87059-0ccb-48ed-9080-3949b075eaa1` → returns the first 10 results after the result with cursor `c4f87059-0ccb-48ed-9080-3949b075eaa1` in the complete result set
* etc.

#### Paginating backwards

* `?last=10` → returns the last 10 results of the complete result set
* `?last10&before=c4f87059-0ccb-48ed-9080-3949b075eaa1` → returns the last 10 results before the result with cursor `c4f87059-0ccb-48ed-9080-3949b075eaa1` in the complete result set
* etc.

When you have fetched one slice of the results and want to fetch the next or previous slice, you will need a cursor, as explained above. Therefore these are returned in the result set, along with booleans that indicate if there is a previous or next page to be fetched. You can find this in the `pageInfo` node, in the response.

* When you want to fetch the previous page, you must set the `before`-filter to `pageInfo.startCursor` of the current response
* When you want to fetch the next page, you must set the `after`-filter to `pageInfo.endCursor` of the current response.

#### Example using the pledges endpoint

1. **First day:** retrieve until `pageInfo.hasNextPage` is `false` in the response, and afterwards store the date and time of now, to be the `releasedAfter`-value for tomorrow.
   * first page: `/api/v1/pledges?releasedAfter=[initial]&first=50`
   * second page: `/api/v1/pledges?releasedAfter=[initial]&first=10&after=41222ef7-a861-4bbd-ae93-2f645336b85d`
   * ...
   * last page: `/api/v1/pledges?releasedAfter=[initial]&first=10&after=10d303b1-4eca-4db4-9ae7-7cd65f98a5b5`
2. **Second day:** retrieve all released after the previous datetime you fetched, retrieve until `pageInfo.hasNextPage` is `false` in the response, and afterwards store the date and time of the last pledge you received.
   * first page: `/api/v1/pledges?releasedAfter=[previousDay]&first=50`
   * second page: `/api/v1/pledges?releasedAfter=[previousDay]&first=10&after=bd82f150-a797-4d9f-af09-c3ea06964e9d`
   * ...
   * last page: `/api/v1/pledges?releasedAfter=[previousDay]&first=10&after=3c53b11a-adef-4dc1-90d7-c23dc0108492`
   *
3. etc.