# How to Implement Pagination for API Responses in the Anthropic Python SDK

> Learn to implement pagination for API responses using the Anthropic Python SDK. Discover automatic handling via page classes and methods for manual traversal.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**The Anthropic Python SDK automatically handles API pagination through specialized page classes defined in [`src/anthropic/pagination.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/pagination.py), which support cursor-based, token-based, and ID-based strategies while exposing `has_next_page()` and `next_page_info()` methods for manual traversal.**

The `anthropics/anthropic-sdk-python` repository provides a robust pagination system that abstracts the complexity of handling large result sets from the Anthropic API. When you implement pagination for API responses using this SDK, the library manages HTTP parameters, request stitching, and result concatenation automatically. Understanding the underlying page classes and iteration methods allows you to process large datasets efficiently in both synchronous and asynchronous applications.

## Core Pagination Classes

The SDK defines six primary page types in [`src/anthropic/pagination.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/pagination.py) that inherit from base classes in [`src/anthropic/_base_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_base_client.py). Each class implements specific logic for determining the next page of results based on the API endpoint's pagination strategy.

### Standard Cursor Pagination

For endpoints using `after_id` or `before_id` cursor fields, the SDK provides **SyncPage** and **AsyncPage**. These classes inspect the current payload for `last_id` or `first_id` fields and construct a `PageInfo` object containing `params={"after_id": last_id}` or `params={"before_id": first_id}` for the subsequent request. This pattern is used by the models listing endpoint.

### Token-Based Pagination

Endpoints returning opaque `next_page` tokens, such as batch results, utilize **SyncTokenPage** and **AsyncTokenPage**. These extract the token from the response and prepare `PageInfo(params={"page_token": next_page})` for continuation. You can see this implementation in [`src/anthropic/resources/beta/files.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/files.py).

### Generic Cursor Pagination

The Beta skills API employs **SyncPageCursor** and **AsyncPageCursor**, which handle generic `next_page` cursors by returning `PageInfo(params={"page": next_page})`. This implementation is found in [`src/anthropic/resources/beta/skills/skills.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/skills/skills.py).

## How the SDK Wires Pagination Together

The pagination flow involves three key steps orchestrated by the base client and resource methods to transform page information into subsequent HTTP requests.

### Resource Method Configuration

Resource methods specify their pagination strategy by passing a page class to `_get_api_list`. In [`src/anthropic/resources/models.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/models.py) (lines 90-102), the list endpoint returns:

```python
return self._get_api_list(
    "/v1/models",
    page=SyncPage[ModelInfo],
    options=make_request_options(...),
    model=ModelInfo,
)

```

The `page=` argument instructs the client which pagination wrapper to instantiate and how to parse the response.

### Request Parsing and Execution

The `_get_api_list` method creates a request parser defined in [`_base_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/_base_client.py) (lines 1236-1245) that attaches private attributes (`_client`, `_model`, `_options`) to the page instance. The generic `PageInfo` type (defined in [`_base_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/_base_client.py) lines 23-71) holds either a full URL, a query-parameter mapping, or a JSON body for the next request.

### Iteration Methods

All page classes expose two critical methods inherited from `BaseSyncPage` and `BaseAsyncPage`:

- `has_next_page() → bool` – Returns true when the response contains items and a non-null next-page indicator.
- `next_page_info() → PageInfo` – Builds the request parameters required for the next API call.

You can iterate **item-wise** using `BaseSyncPage.__iter__`, which yields each item from every fetched page by internally calling `iter_pages` and `next_page_info`. Alternatively, iterate **page-wise** using `iter_pages()` to access raw page objects and inspect pagination metadata such as `page.last_id` or `page.has_more`.

## Practical Implementation Examples

### Synchronous Item-Wise Iteration

To automatically fetch all models across multiple pages:

```python
import anthropic

client = anthropic.Anthropic(api_key="YOUR_API_KEY")

# Automatically handles pagination

for model in client.models.list():
    print(model.id, model.name)

```

### Page-Wise Manual Control

To process pages individually and check for additional results:

```python
pages = client.models.list()
for page in pages.iter_pages():
    print("=== New page ===")
    for model in page.data:
        print(model.id)
    
    # Check if another request will be made

    if page.has_next_page():
        next_info = page.next_page_info()
        print(f"Next page params: {next_info}")

```

### Asynchronous Streaming

For non-blocking pagination:

```python
import anthropic
import asyncio

async def list_models():
    client = anthropic.AsyncAnthropic(api_key="YOUR_API_KEY")
    async for model in client.models.list():
        print(model.id, model.name)

asyncio.run(list_models())

```

### Manual Token-Based Traversal

For endpoints like batch results that use tokens:

```python
batch_page = client.batch_results.list()
while batch_page:
    for batch in batch_page.data:
        process(batch)
    if not batch_page.has_next_page():
        break
    batch_page = batch_page.get_next_page()

```

### Beta Skills Cursor Pagination

Using the cursor-based Beta API:

```python
skills = client.beta.skills.list()
for skill in skills:
    print(skill.id, skill.name)

```

## Summary

- The Anthropic SDK automatically implements pagination for API responses through generic page classes in [`src/anthropic/pagination.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/pagination.py).
- Six primary classes handle different strategies: `SyncPage`/`AsyncPage` for ID cursors, `SyncTokenPage`/`AsyncTokenPage` for tokens, and `SyncPageCursor`/`AsyncPageCursor` for generic cursors.
- The `has_next_page()` and `next_page_info()` methods provide manual control over pagination traversal.
- Resource methods declare pagination types via the `page=` parameter in `_get_api_list`, as seen in [`src/anthropic/resources/models.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/models.py).
- Both item-wise (`for item in page`) and page-wise (`for page in pages.iter_pages()`) iteration patterns are supported for synchronous and asynchronous clients.

## Frequently Asked Questions

### How does the Anthropic SDK determine when more pages are available?

The SDK checks the `has_next_page()` method, which returns true only if the current response contains data and includes a non-null pagination indicator. Depending on the endpoint type, this may check for `last_id`, `next_page`, or `has_more` fields in the response payload.

### Can I manually fetch the next page instead of using automatic iteration?

Yes. After checking `has_next_page()`, call the `get_next_page()` method on any page instance to retrieve the subsequent page object. This executes the next request immediately using the parameters built by `next_page_info()`.

### What is the difference between SyncPage and SyncTokenPage?

`SyncPage` handles cursor-based pagination using `after_id` or `before_id` parameters extracted from `last_id` or `first_id` fields in the response. `SyncTokenPage` manages endpoints that return opaque `next_page` tokens, constructing requests with `page_token` parameters instead.

### Where is the core pagination logic implemented in the SDK source code?

Core pagination infrastructure resides in [`src/anthropic/_base_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_base_client.py), which defines `BaseSyncPage`, `BaseAsyncPage`, and the `PageInfo` type. Specific page type implementations are located in [`src/anthropic/pagination.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/pagination.py), while resource-specific usage examples appear in files like [`src/anthropic/resources/models.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/models.py) and [`src/anthropic/resources/beta/skills/skills.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/skills/skills.py).