Pagination

Response Format

Paginated endpoints use offset-based pagination with 1-indexed page numbers. Responses include pagination metadata alongside the items:

{
    "success": true,
    "data": {
        "items": [],
        "pagination": {
            "total_items": 142,
            "total_pages": 15,
            "current_page": 1,
            "page_size": 10,
            "has_next": true,
            "has_previous": false
        }
    },
    "timestamp": "2025-10-15T10:00:00Z"
}

Auto-Pagination

The simplest way to iterate through all results. The SDK automatically fetches subsequent pages as needed.

for rec in client.recommendations.list(page_size=50):
    print(rec.recommendation_id)

Async (Python)

async for rec in await async_client.recommendations.list(page_size=50):
    print(rec.recommendation_id)

Collect All Items

Fetch every page and return all items as a single collection. Use with caution on large datasets.

all_recs = list(client.recommendations.list(page_size=100))

Page-Level Iteration

Iterate one page at a time to process results in batches.

for page in client.recommendations.list(page_size=50).iter_pages():
    print(f"Processing {len(page.items)} items")
    for item in page.items:
        process(item)

Async Pages (Python)

async for page in (await async_client.recommendations.list(page_size=50)).iter_pages():
    print(f"Processing {len(page.items)} items")

Manual Pagination

For full control, pass page and page_size directly and handle navigation yourself.

page = client.recommendations.list(page=1, page_size=50)
while page:
    for item in page.items:
        process(item)
    page = page.next_page()

Paginated Endpoints

These methods return paginated results:

Resource	Method	Python	TypeScript	Go
Recommendations	List	`recommendations.list()`	`recommendations.list()`	`Recommendations.List()`
Savings	List	`savings.list()`	`savings.list()`	`Savings.List()`
Providers	List Recommendations	`providers.list_recommendations()`	`providers.listRecommendations()`	`Providers.ListRecommendations()`
Providers	List Realized Savings	`providers.list_realized_savings()`	`providers.listRealizedSavings()`	`Providers.ListRealizedSavings()`
Providers	List Potential Savings	`providers.list_potential_savings()`	`providers.listPotentialSavings()`	`Providers.ListPotentialSavings()`

Defaults

Parameter	Default	Maximum
`page`	1	-
`page_size`	10	100

Pagination

On this page