# 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.


---

# 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://developer.tapraise.com/api/api-overview/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.