Principle:Anthropics Anthropic sdk python Pagination And Iteration

Knowledge Sources	Anthropic Python SDK Anthropic API Docs
Domains	SDK Architecture, Pagination
Last Updated	2026-02-15 00:00 GMT

Overview

The Pagination And Iteration principle describes how the Anthropic Python SDK implements cursor-based pagination strategies for automatic multi-page API result iteration. The SDK provides SyncPage/AsyncPage and SyncCursorPage/AsyncCursorPage classes that implement __iter__/__aiter__ for transparent pagination. Cursor-based iteration automatically fetches subsequent pages using has_more flags and cursor tokens, allowing callers to iterate over arbitrarily large result sets with a simple for loop.

Theoretical Basis

Cursor-Based Pagination Model

The SDK adopts cursor-based pagination rather than offset-based pagination. In this model, each page response includes:

• data -- The list of items on the current page.
• has_more -- A boolean indicating whether additional pages exist.
• first_id / last_id -- Cursor tokens pointing to the first and last items on the page.

To fetch the next page, the SDK sends the last_id from the current page as the after parameter in the subsequent request. This approach has several advantages over offset-based pagination:

• Consistency -- Cursor pagination is stable in the presence of insertions and deletions. An offset-based approach can skip or duplicate items when the underlying dataset changes between page fetches.
• Performance -- The API server can use the cursor token to seek directly to the correct position, avoiding the cost of scanning and discarding offset rows.

Transparent Iteration Protocol

The SyncCursorPage and AsyncCursorPage classes implement Python's iterator protocols:

# Synchronous iteration
for model in client.models.list():
    print(model.id)

# Asynchronous iteration
async for model in async_client.models.list():
    print(model.id)

The iterator automatically fetches subsequent pages as the caller consumes items. This means:

• No manual page management -- The caller does not need to track cursors, construct next-page requests, or check termination conditions.
• Lazy fetching -- The next page is only fetched when the current page's items are exhausted, minimizing unnecessary API calls.
• Memory efficiency -- Only one page of results is held in memory at a time.

Page Object as a First-Class Container

Each page object (SyncPage, SyncCursorPage) is itself a valid container that exposes the current page's items through the data attribute. Callers who want explicit page-level control can use the page object directly without engaging the automatic iteration:

page = client.models.list()
# Access current page items
for item in page.data:
    process(item)
# Manually check for more pages
if page.has_more:
    next_page = page.get_next_page()

This dual interface -- automatic iteration for convenience, explicit page access for control -- follows the principle of progressive disclosure.

Sync and Async Duality

The pagination system mirrors the SDK's broader sync/async duality:

• SyncPage and SyncCursorPage implement __iter__ and return synchronous iterators.
• AsyncPage and AsyncCursorPage implement __aiter__ and return asynchronous iterators.

Both families share the same pagination logic and page-parsing code, differing only in their use of await for HTTP fetches. This ensures behavioral parity between sync and async code paths.

Design Constraints

• The has_more field is the authoritative termination signal. An empty data list alone does not guarantee that no more pages exist.
• Cursor tokens are opaque strings. The SDK does not parse or interpret their contents; it simply passes them back to the API as query parameters.
• Page size is controlled by the API server's default or by an explicit limit parameter in the request. The SDK does not impose its own page-size limits.
• Automatic iteration creates a new HTTP request for each subsequent page. Callers should be aware of rate-limiting implications when iterating over large collections.

Related Pages

Implemented By

• Implementation:Anthropics_Anthropic_sdk_python_Pagination