---
title: "SDK Pagination"
description: "Auto-paging via the SDK's Page helper."
section: "Libraries"
group: "SDK"
---

# SDK Pagination

Every `list()` method returns a [`Page<T>`](/types/index) — an object that holds one page of results plus helpers for walking to the next one.

## Page shape

```ts
import Aeontel, { type Page } from "@aeontel/sdk";
import type { Agent } from "@aeontel/sdk";

const client = new Aeontel("sec_...");
const page: Page<Agent> = await client.agents.list({ workspace_id: "wsp_..." });

page.data; // Agent[]
page.pageInfo; // { total, limit, offset, hasMore, sortBy, order }
```

## Query parameters

The common parameters accepted by every list endpoint:

| Param     | Type              | Notes                                            |
| --------- | ----------------- | ------------------------------------------------ |
| `limit`   | number            | Max items per page (default 50)                  |
| `offset`  | number            | Skip this many items                             |
| `sort_by` | string            | Field name, see each resource for allowed values |
| `order`   | `"asc" \| "desc"` | Default `"desc"`                                 |

Resource-specific filters (e.g. `workspace_id`, `status`) go alongside these.

## Manual paging

```ts
let page = await client.runs.list({
  workspace_id: "wsp_...",
  status: "running",
});
while (page.hasNextPage()) {
  page = await page.getNextPage();
  console.log(`Loaded ${page.data.length} more runs.`);
}
```

## Auto-iteration

`Page` is `AsyncIterable`, so you can `for await` across every page transparently.

```ts
const page = await client.events.list({ workspace_id: "wsp_..." });
for await (const event of page) {
  if (event.type === "run.completed") handleCompleted(event);
}
```

Breaking out of the loop stops fetching — there's no work wasted.