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

# Pagination

> Learn how to identify the best API pagination type for your integration

## Overview

RWS supports the main pagination methods for APIs, like simple, by offset, by cursor and by last ID, allowing efficient extraction of large volumes of data.

## Pagination types supported by RWS

<CardGroup cols={2}>
  <Card title="Simple Pagination" icon="list-ol" href="#simple-pagination">
    Page number and page size based
  </Card>

  <Card title="Offset Pagination" icon="sort-numeric-up" href="#offset-pagination">
    Uses offset and limit parameters
  </Card>

  <Card title="Cursor Pagination" icon="location-arrow" href="#cursor-pagination">
    Token-based pagination
  </Card>

  <Card title="Last ID Pagination" icon="hashtag" href="#last-id-pagination">
    Uses last record ID for next page
  </Card>
</CardGroup>

## Simple Pagination

Simple pagination uses page number and page size parameters to fetch data in chunks. It's the most common pagination type.

### How to identify

Your API uses simple pagination if:

* Query parameters include `page`, `page_number`, `pageNo`, or similar
* The API accepts both page number and page size parameters together
* Example URLs: `?page=1&limit=10`, `?page_number=2&page_size=50`

### How it works

The API expects two parameters:

* **Page number**: Which page to retrieve (usually starts at 1 or 0)
* **Page size**: How many records per page

Increment the page number for each subsequent request. The API returns pages until no more data is available.

| Request | Parameter                    | Page returned            |
| ------- | ---------------------------- | ------------------------ |
| First   | `GET /items?page=1&limit=10` | Page 1                   |
| Second  | `GET /items?page=2&limit=10` | Page 2                   |
| Third   | `GET /items?page=3&limit=10` | Page 3 (or no more data) |

## Offset Pagination

Offset pagination uses an offset (starting position) and limit (number of records) to retrieve data.

### How to identify

Your API uses offset pagination if:

* Query parameters include `offset`, `skip`, `start`, or similar
* The API uses offset combined with limit to control pagination
* Example URLs: `?offset=0&limit=10`, `?skip=20&take=50`

### How it works

The API expects:

* **Offset**: The number of records to skip before starting to return results
* **Limit**: The maximum number of records to return

Increase the offset by the limit amount for each subsequent page. For example, with limit=10: first page uses offset=0, second uses offset=10, third uses offset=20.

| Request | Parameter                       | Offset returned             |
| ------- | ------------------------------- | --------------------------- |
| First   | `GET /items?offset=0&limit=10`  | offset=0                    |
| Second  | `GET /items?offset=10&limit=10` | offset=10                   |
| Third   | `GET /items?offset=20&limit=10` | offset=20 (or no more data) |

## Cursor Pagination

Cursor pagination uses a token or cursor value to mark the position in the dataset.

### How to identify

Your API uses cursor pagination if:

* The API response includes a cursor, token, or "next" field pointing to the next page
* Response includes fields like `nextCursor`, `pageToken`, `next`, `cursor`, or `pagination.next`
* You need to pass a token from the previous response to get the next page
* Example: Response contains `{"data": [...], "pagination": {"nextCursor": "abc123"}}`

### How it works

The API provides a cursor or token in the response that points to the next page. The cursor can be either a token (string value) or a URL pointing to the next page. Extract the cursor from the current response and include it in your next request. The API uses this cursor to determine which records to return next.

Each response contains a token that points to the next page. Use this token as a parameter in the next request.

| Request | Parameter                           | Response cursor          |
| ------- | ----------------------------------- | ------------------------ |
| First   | `GET /items?limit=10`               | `"nextCursor": "abc123"` |
| Second  | `GET /items?limit=10&cursor=abc123` | `"nextCursor": "xyz789"` |
| Third   | `GET /items?limit=10&cursor=xyz789` | `"nextCursor": null`     |

Pagination ends when the returned cursor is null or absent.

## Last ID Pagination

Last ID pagination uses the ID of the last record from the current page to fetch the next page.

### How to identify

Your API uses last ID pagination if:

* Query parameters include `after`, `since_id`, `last_id`, or similar
* The API requires passing the ID of the last record from the previous page
* Records are ordered by ID and you fetch records with IDs greater than a given value
* Example URLs: `?after=12345&limit=10`, `?since_id=67890&per_page=50`

### How it works

Extract the ID of the last record from the current page and use it as a parameter to fetch the next page. The API returns records with IDs greater than the provided ID value. This approach prevents missing records even if new data is added while paginating, since you're always fetching records after a specific ID.

| Request | Parameter                       | Last ID returned                 |
| ------- | ------------------------------- | -------------------------------- |
| First   | `GET /items?limit=10`           | `lastId: 100`                    |
| Second  | `GET /items?limit=10&after=100` | `lastId: 200`                    |
| Third   | `GET /items?limit=10&after=200` | `lastId: null` (or no more data) |

Pagination ends when there are no more records with an ID greater than the last ID provided.

## Datapoint path in the response

The **Datapoint path in the response** field tells RWS where the records live inside each page's response body.

* `root`: the response body itself is the record (or the array of records)
* A dot-notation path, e.g. `data.items` when the response looks like `{"data": {"items": [...]}}`

The guides in these docs use `root` because JSONPlaceholder returns the records directly as the response body.

## Pagination end

The **Pagination end type** field defines how RWS detects the last page:

| End type | Behavior                                                                                                                                                                        |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Object   | Pagination ends when a page contains no more records at the datapoint path (an empty page)                                                                                      |
| Status   | Pagination ends when the source responds with a specific HTTP status, configured alongside the end type. That status is treated as a normal end-of-data marker, not as an error |

### Repeated page protection

If a source ignores its pagination parameter and returns the exact same page twice in a row, RWS stops the extraction with a descriptive error instead of looping forever. If you see this error, check that the source API actually honors the configured page or offset parameter.