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

# TypeScript Pagination

> Iterate through paginated results with the DevHelm TypeScript SDK

List endpoints return paginated results. The SDK provides auto-fetching for convenience and manual page control for large datasets.

## Auto-fetch all pages

The `list()` method automatically fetches all pages and returns a flat array:

```typescript theme={null}
const monitors = await client.monitors.list();
// monitors: MonitorDto[] — all monitors, not just the first page
```

Internally, the SDK requests pages of 200 items and loops until `hasNext` is false.

## Manual page control

Use `listPage()` when you need control over pagination:

```typescript theme={null}
import type { Page } from "@devhelm/sdk";

const page: Page<MonitorDto> = await client.monitors.listPage(0, 50);

console.log(page.data);     // MonitorDto[]
console.log(page.hasNext);  // boolean
console.log(page.hasPrev);  // boolean
```

### Page type

```typescript theme={null}
interface Page<T> {
  data: T[];
  hasNext: boolean;
  hasPrev: boolean;
  totalElements: number | null;
  totalPages: number | null;
}
```

`totalElements` and `totalPages` are populated when the API can return a count efficiently; they're `null` for cursor-friendly endpoints that skip the count.

### Iterate through all pages manually

```typescript theme={null}
let page = 0;
const allMonitors: MonitorDto[] = [];

while (true) {
  const result = await client.monitors.listPage(page, 100);
  allMonitors.push(...result.data);
  if (!result.hasNext) break;
  page++;
}
```

## Cursor pagination

Check results use cursor-based pagination for efficient streaming through large result sets:

```typescript theme={null}
import type { CursorPage } from "@devhelm/sdk";

const results: CursorPage<CheckResultDto> = await client.monitors.results(42, {
  limit: 50,
});

console.log(results.data);       // CheckResultDto[]
console.log(results.nextCursor); // string | null
console.log(results.hasMore);    // boolean
```

### CursorPage type

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

### Iterate with cursor

```typescript theme={null}
let cursor: string | undefined;
const allResults: CheckResultDto[] = [];

do {
  const page = await client.monitors.results(42, { cursor, limit: 100 });
  allResults.push(...page.data);
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

## Which endpoints use which pagination

| Method                           | Pagination type           | Default size |
| -------------------------------- | ------------------------- | ------------ |
| `*.list()`                       | Offset (auto-fetches all) | 200 per page |
| `*.listPage(page, size)`         | Offset (manual)           | —            |
| `monitors.results(id, options)`  | Cursor                    | —            |
| `monitors.versions(id, options)` | Offset                    | 20           |

## Next steps

<CardGroup cols={2}>
  <Card title="Client reference" icon="book" href="/sdk/typescript/client-reference">
    Full method reference for all namespaces.
  </Card>

  <Card title="Pagination patterns" icon="book" href="/patterns/pagination">
    REST API pagination patterns.
  </Card>
</CardGroup>