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

# Pagination

> Navigate through large datasets efficiently

The SDK supports multiple pagination methods for handling large datasets.

## Cursor-Based Pagination (Recommended)

Best for real-time data and large datasets. Uses an opaque cursor to track position.

```typescript theme={null}
const page1 = await sdk.clients.list({ limit: 20 });

console.log(page1.data); // First 20 clients
console.log(page1.pagination.hasMore); // true if more pages exist
console.log(page1.pagination.nextCursor); // Cursor for next page

if (page1.pagination.hasMore) {
  const page2 = await sdk.clients.list({
    cursor: page1.pagination.nextCursor,
    limit: 20,
  });
}
```

<Info>
  Cursor-based pagination is stable even when records are added or removed
  between requests.
</Info>

## Async Iterator (Auto-Pagination)

Process all records without managing pagination manually:

```typescript theme={null}
for await (const client of sdk.clients.iterate()) {
  console.log(client.name);
}
```

With filtering:

```typescript theme={null}
for await (const client of sdk.clients.iterate({ type: "individual" })) {
  await processClient(client);
}
```

The iterator automatically fetches subsequent pages as you iterate.

## Pagination Utilities

The SDK provides helpers for common pagination patterns:

```typescript theme={null}
import { collectAll, collectUpTo, getFirst } from "@artu-ai/compliance-sdk";
```

### Collect All

Collect all items into an array:

```typescript theme={null}
const allClients = await collectAll(sdk.clients.iterate());
console.log(`Total: ${allClients.length} clients`);
```

<Warning>
  Use with caution on large datasets. Consider using `collectUpTo` or the async
  iterator for large collections.
</Warning>

### Collect Up To N

Collect a maximum number of items:

```typescript theme={null}
const first100 = await collectUpTo(sdk.clients.iterate(), 100);
```

### Get First

Get just the first item:

```typescript theme={null}
const firstClient = await getFirst(sdk.clients.iterate());

if (firstClient) {
  console.log(firstClient.name);
}
```

## Offset-Based Pagination

For UI pagination with page numbers:

```typescript theme={null}
const pageSize = 20;
const pageNumber = 3;

const page = await sdk.clients.list({
  offset: (pageNumber - 1) * pageSize,
  limit: pageSize,
});
```

<Warning>
  Offset pagination is less efficient for large datasets and can skip or
  duplicate records if data changes between requests.
</Warning>

## Constants

```typescript theme={null}
import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from "@artu-ai/compliance-sdk";

console.log(DEFAULT_PAGE_SIZE); // 20
console.log(MAX_PAGE_SIZE); // 200
```

## Comparison

| Method   | Best For                        | Stability | Performance |
| -------- | ------------------------------- | --------- | ----------- |
| Cursor   | API consumption, real-time data | High      | Excellent   |
| Iterator | Processing all records          | High      | Excellent   |
| Offset   | UI pagination, small datasets   | Low       | Good        |

## Pagination Response

All `list()` methods return a paginated response:

```typescript theme={null}
interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    hasMore: boolean;
    nextCursor?: string;
  };
}
```

## Full Example

Processing all clients in batches:

```typescript theme={null}
import { collectUpTo } from "@artu-ai/compliance-sdk";

// Process in batches of 100
async function processAllClients() {
  let processed = 0;

  for await (const client of sdk.clients.iterate()) {
    await processClient(client);
    processed++;

    if (processed % 100 === 0) {
      console.log(`Processed ${processed} clients...`);
    }
  }

  console.log(`Done! Processed ${processed} clients total.`);
}

// Or with manual cursor pagination
async function processWithCursor() {
  let cursor: string | undefined;
  let total = 0;

  do {
    const { data, pagination } = await sdk.clients.list({
      cursor,
      limit: 100,
    });

    for (const client of data) {
      await processClient(client);
    }

    total += data.length;
    cursor = pagination.nextCursor;

    console.log(`Processed ${total} clients...`);
  } while (cursor);
}
```