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

# Pagination

> Paginate through large result sets with the SDK.

Most `list()` methods return paginated results. The SDK uses a page-based pagination model.

## Pagination Options

Pass `page` and `perPage` to control pagination:

```js theme={null}
import { Royaltyport } from '@royaltyport/sdk';

const royaltyport = new Royaltyport({
  apiKey: 'rp_your_token_here',
});

const { data } = await royaltyport.artists.list('project-id', {
  page: 1,
  perPage: 50,
});
```

| Option    | Type     | Default | Description               |
| --------- | -------- | ------- | ------------------------- |
| `page`    | `number` | `1`     | Page number (1-indexed)   |
| `perPage` | `number` | `20`    | Items per page (max: 100) |

***

## Paginated Result

Paginated responses include the items and metadata for navigating pages:

| Field         | Type     | Description                            |
| ------------- | -------- | -------------------------------------- |
| `items`       | `array`  | The items on the current page          |
| `total_count` | `number` | Total number of items across all pages |
| `page`        | `number` | Current page number                    |
| `per_page`    | `number` | Items per page                         |

```js theme={null}
import { Royaltyport } from '@royaltyport/sdk';

const royaltyport = new Royaltyport({
  apiKey: 'rp_your_token_here',
});

const { data } = await royaltyport.artists.list('project-id');

console.log(data.items);       // the artists on this page
console.log(data.total_count); // 150
console.log(data.page);        // 1
console.log(data.per_page);    // 20
```

***

## Iterating All Pages

To fetch all items across pages:

```js theme={null}
import { Royaltyport } from '@royaltyport/sdk';

const royaltyport = new Royaltyport({
  apiKey: 'rp_your_token_here',
});

const allArtists = [];
let page = 1;
const perPage = 100;

while (true) {
  const { data } = await royaltyport.artists.list('project-id', { page, perPage });
  allArtists.push(...data.items);

  if (allArtists.length >= data.total_count) break;
  page++;
}

console.log(`Fetched ${allArtists.length} artists`);
```

<Note>
  The `projects.list()` method returns an array directly (not paginated), since projects are typically few.
</Note>