Implementation:Anthropics Anthropic sdk python Pagination

Knowledge Sources	Anthropic SDK Python
Domains	API_Client, Data_Iteration
Last Updated	2026-02-15 12:00 GMT

Overview

The pagination.py module defines six paginated response classes that enable automatic iteration over multi-page API results using cursor-based, token-based, and page-cursor pagination strategies.

Description

The Anthropic API returns paginated results for list endpoints, where each response page contains a data array of items along with pagination metadata. This module provides three pairs of synchronous/asynchronous page classes, each implementing a different pagination strategy.

SyncPage / AsyncPage implement cursor-based pagination using first_id and last_id fields. When iterating forward, the last_id of the current page becomes the after_id parameter for the next request. When iterating backward (when before_id is in the request params), the first_id becomes the before_id for the next request. This is the primary pagination strategy for most Anthropic list endpoints.

SyncTokenPage / AsyncTokenPage implement token-based pagination using a next_page opaque token. Each response includes a token that is passed as the page_token parameter to fetch the next page. This strategy is used for endpoints that provide an opaque continuation token rather than item IDs.

SyncPageCursor / AsyncPageCursor implement simple page-cursor pagination where the next_page field contains a page identifier that is passed as the page parameter. This is similar to token-based pagination but uses a different parameter name.

All six classes share the same core logic: they extend BaseSyncPage or BaseAsyncPage (from _base_client), expose a data: List[_T] field, a has_more: Optional[bool] flag that short-circuits pagination when explicitly False, and implement _get_page_items(), has_next_page(), and next_page_info() to drive the base class iteration machinery.

Usage

These classes are returned by SDK list methods (e.g., client.models.list()). Users iterate over them directly using for / async for loops; the SDK handles fetching subsequent pages automatically.

Code Reference

Source Location

• Repository: Anthropic SDK Python
• File: src/anthropic/pagination.py

Signature

class SyncPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool] = None
    first_id: Optional[str] = None
    last_id: Optional[str] = None

    def _get_page_items(self) -> List[_T]: ...
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

class AsyncPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool] = None
    first_id: Optional[str] = None
    last_id: Optional[str] = None

    def _get_page_items(self) -> List[_T]: ...
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

class SyncTokenPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool] = None
    next_page: Optional[str] = None

    def _get_page_items(self) -> List[_T]: ...
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

class AsyncTokenPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool] = None
    next_page: Optional[str] = None

    def _get_page_items(self) -> List[_T]: ...
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

class SyncPageCursor(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool] = None
    next_page: Optional[str] = None

    def _get_page_items(self) -> List[_T]: ...
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

class AsyncPageCursor(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool] = None
    next_page: Optional[str] = None

    def _get_page_items(self) -> List[_T]: ...
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

Import

from anthropic.pagination import SyncPage, AsyncPage
from anthropic.pagination import SyncTokenPage, AsyncTokenPage
from anthropic.pagination import SyncPageCursor, AsyncPageCursor

I/O Contract

Page Response Fields

Field	Type	Present In	Description
data	List[_T]	All page types	The list of items on this page
has_more	Optional[bool]	All page types	If explicitly False, stops pagination; otherwise delegates to base class
first_id	Optional[str]	SyncPage, AsyncPage	ID of the first item on this page (for backward pagination)
last_id	Optional[str]	SyncPage, AsyncPage	ID of the last item on this page (for forward pagination)
next_page	Optional[str]	Token and Cursor page types	Opaque token or cursor for the next page

Pagination Strategy Mapping

Page Class	Strategy	Next Page Parameter	Parameter Value Source
SyncPage / AsyncPage	Cursor (forward)	after_id	last_id from current page
SyncPage / AsyncPage	Cursor (backward)	before_id	first_id from current page
SyncTokenPage / AsyncTokenPage	Token	page_token	next_page from current page
SyncPageCursor / AsyncPageCursor	Page cursor	page	next_page from current page

Method Contract

Method	Returns	Description
_get_page_items()	List[_T]	Returns self.data or empty list if data is falsy
has_next_page()	bool	Returns False if has_more is explicitly False; otherwise delegates to super().has_next_page()
next_page_info()	Optional[PageInfo]	Returns a PageInfo with the appropriate params for the next page, or None if no more pages

Usage Examples

import anthropic

client = anthropic.Anthropic()

# Automatic iteration over all pages (synchronous)
# The SDK fetches subsequent pages transparently
for model in client.models.list():
    print(model.id)

# Access a single page directly
page = client.models.list()
print(page.data)       # Items on this page
print(page.has_more)   # Whether more pages exist
print(page.first_id)   # ID of first item
print(page.last_id)    # ID of last item

# Async iteration
async_client = anthropic.AsyncAnthropic()

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

# Manual page-by-page iteration
page = client.models.list()
while page.has_next_page():
    page = page.get_next_page()
    for item in page.data:
        print(item.id)

Related Pages

Related Implementations

• Implementation:Anthropics_Anthropic_sdk_python_Anthropic_Client_Init -- Client that returns paginated responses
• Implementation:Anthropics_Anthropic_sdk_python_Package_Init -- Top-level namespace