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

The Anthropic Python SDK automatically handles API pagination through specialized page classes defined in 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 that inherit from base classes in 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.

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.

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 (lines 90-102), the list endpoint returns:

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 (lines 1236-1245) that attaches private attributes (_client, _model, _options) to the page instance. The generic PageInfo type (defined in _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:

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:

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:

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:

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:

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.
• 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.
• 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, which defines BaseSyncPage, BaseAsyncPage, and the PageInfo type. Specific page type implementations are located in src/anthropic/pagination.py, while resource-specific usage examples appear in files like src/anthropic/resources/models.py and src/anthropic/resources/beta/skills/skills.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}