Implementation:Googleapis Python genai Pager

Knowledge Sources	Googleapis_Python_genai
Domains	Pagination, API_Infrastructure
Last Updated	2026-02-15 14:00 GMT

Overview

Concrete tool for paginating through list API endpoint results provided by the Google Gen AI SDK.

Description

The Pager and AsyncPager classes provide generic pagination support for all list operations in the SDK (models, files, caches, batches, tuning jobs, etc.). They implement Python iterator protocols, allowing seamless iteration over all items across multiple API pages. The _BasePager base class handles page state, item indexing, and next-page fetching.

Usage

These classes are returned automatically by all list methods (e.g. client.models.list(), client.files.list()). Use them when iterating over results that may span multiple API pages.

Code Reference

Source Location

• Repository: Googleapis_Python_genai
• File: google/genai/pagers.py
• Lines: 38-268 (_BasePager at L38-165, Pager at L168-209, AsyncPager at L211-268)

Signature

class Pager(_BasePager[T]):
    def __next__(self) -> T: ...
    def __iter__(self) -> Iterator[T]: ...
    def next_page(self) -> list[T]: ...

class AsyncPager(_BasePager[T]):
    def __aiter__(self) -> AsyncIterator[T]: ...
    async def __anext__(self) -> T: ...
    async def next_page(self) -> list[T]: ...

Import

from google.genai.pagers import Pager, AsyncPager

I/O Contract

Inputs

Name	Type	Required	Description
name	PagedItem	Yes (internal)	Resource type identifier for response parsing
request	Callable	Yes (internal)	Function to call for next page
response	Any	Yes (internal)	Initial API response
config	Any	Yes (internal)	Request configuration for pagination

Outputs

Name	Type	Description
__iter__/__aiter__ yields	T	Individual items from paginated results
next_page() returns	list[T]	Next page of results
page property	list[T]	Current page items
page_size property	int	Number of items in current page

Usage Examples

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

# Iterate over all models (auto-paginates)
for model in client.models.list():
    print(model.name)

# Access page-level information
pager = client.models.list()
print(f"First page has {pager.page_size} items")
print(f"Total items accessible via indexing: pager[0]")

# Manually advance pages
next_items = pager.next_page()

Related Pages

• Environment:Googleapis_Python_genai_Python_3_10_SDK_Runtime