Implementation:Openai Openai python API Pagination

Knowledge Sources	Openai_Openai_python
Domains	SDK_Infrastructure
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for API response pagination provided by the openai-python SDK.

Description

The pagination module defines page wrapper classes for iterating over paginated API responses. SyncPage and AsyncPage represent non-paginated list responses (with data and object fields) that exist for forwards-compatibility; their next_page_info() always returns None. SyncCursorPage and AsyncCursorPage implement cursor-based pagination using the has_more flag and the id field of the last item in data as the after cursor parameter. SyncConversationCursorPage and AsyncConversationCursorPage are a variant that uses a dedicated last_id field instead of extracting the ID from items. All classes inherit from BaseSyncPage or BaseAsyncPage (from _base_client) and implement _get_page_items() and next_page_info(). The CursorPageItem protocol requires items to have an optional id attribute.

Usage

Use these classes as the page type when calling list endpoints. The SDK automatically wraps API responses in the appropriate page class, enabling iteration via for item in page or async for item in page.

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/pagination.py
• Lines: 1-190

Signature

@runtime_checkable
class CursorPageItem(Protocol):
    id: Optional[str]

class SyncPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    object: str
    def _get_page_items(self) -> List[_T]: ...
    def next_page_info(self) -> None: ...

class AsyncPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    object: str
    def _get_page_items(self) -> List[_T]: ...
    def next_page_info(self) -> None: ...

class SyncCursorPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool]
    def next_page_info(self) -> Optional[PageInfo]: ...

class AsyncCursorPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool]
    def next_page_info(self) -> Optional[PageInfo]: ...

class SyncConversationCursorPage(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool]
    last_id: Optional[str]

class AsyncConversationCursorPage(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
    data: List[_T]
    has_more: Optional[bool]
    last_id: Optional[str]

Import

from openai.pagination import SyncPage, AsyncPage, SyncCursorPage, AsyncCursorPage

I/O Contract

Inputs

Name	Type	Required	Description
data	List[_T]	Yes	The list of items in the current page
has_more	bool or None	No	Whether more pages exist (cursor pages only)
object	str	Yes (SyncPage/AsyncPage)	Object type identifier from the API response
last_id	str or None	No	Last item ID for ConversationCursorPage pagination

Outputs

Name	Type	Description
_get_page_items()	List[_T]	The items in the current page
next_page_info()	PageInfo or None	Cursor parameters for fetching the next page, or None if no more pages
has_next_page()	bool	Whether another page of results is available

Usage Examples

Basic Usage

from openai import OpenAI

client = OpenAI()

# Auto-pagination with cursor pages
page = client.files.list()
for file_obj in page:
    print(file_obj.id, file_obj.filename)

# Manual pagination
page = client.fine_tuning.jobs.list(limit=10)
while page.has_next_page():
    page = page.get_next_page()
    for job in page.data:
        print(job.id)

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus