---
title: Pagination | Boltz API Docs
description: List endpoints are cursor-paginated; the SDK iterates across pages for you, or you can page manually.
---

Every list endpoint (`list` and `list_results`) is **cursor-paginated**. You almost never page by hand: the SDK’s list methods return an iterator that fetches each page as you go.

## Iterate automatically

```
# Walks every result across all pages, fetching more as needed.
for result in client.protein.design.list_results(design_id):
    print(result.id, result.metrics.binding_confidence)
```

```
# Async clients use `async for`.
async for result in client.protein.design.list_results(design_id):
    ...
```

## Cursors and page fields

If you call the endpoints directly (or want explicit control), pagination is id-cursor based:

| Field                  | Where    | Meaning                                                                       |
| ---------------------- | -------- | ----------------------------------------------------------------------------- |
| `limit`                | request  | Max items per page (defaults to 100).                                         |
| `after_id`             | request  | Return items after this id. Pass the previous page’s `last_id` to go forward. |
| `before_id`            | request  | Return items before this id. Pass `first_id` to go backward.                  |
| `data`                 | response | The items in this page.                                                       |
| `has_more`             | response | Whether another page exists.                                                  |
| `last_id` / `first_id` | response | Cursors for the next / previous page.                                         |

Terminal window

```
# First page, then the next one via the returned cursor.
curl "https://api.boltz.bio/compute/v1/protein/design/$RUN_ID/results?limit=100" \
  -H "x-api-key: $BOLTZ_API_KEY"


curl "https://api.boltz.bio/compute/v1/protein/design/$RUN_ID/results?limit=100&after_id=$LAST_ID" \
  -H "x-api-key: $BOLTZ_API_KEY"
```

## Page manually in the SDK

When you need fine-grained control, the page object exposes the cursor directly:

```
page = client.protein.design.list_results(design_id)
print(page.data, page.last_id)


while page.has_next_page():
    page = page.get_next_page()
    print(len(page.data))
```

`get_next_page()` raises if there is no next page, so guard it with `has_next_page()` (use `await` on the async client).

`admin.usage.list` is the one exception: it uses an opaque `page` token (`page` request param, `next_page` in the response) instead of `after_id` / `before_id`. Auto-iteration works the same way.