Pagination

Pagination

Overview

All list() methods in the SDK return paginated results using PageResponse. The SDK provides two approaches: manual page-by-page navigation and automatic iteration over all pages.

PageRequest

Control pagination with these parameters:

Parameter	Type	Default	Description
page	int	1	Page number (1-based)
page_size	int	25	Items per page

PageResponse

The response object:

Property	Type	Description
data	list[dict]	Items on the current page
total	int	Total number of items
page	int	Current page number
page_size	int	Items per page
total_pages	int	Total number of pages
has_next	bool	Whether a next page exists
has_previous	bool	Whether a previous page exists

Manual Pagination

# Fetch a specific page
page = client.hr.employees.list(page=1, page_size=50)

print(f"Page {page.page} of {page.total_pages}")
print(f"Showing {len(page.data)} of {page.total} employees")

for employee in page.data:
    print(employee["first_name"], employee["last_name"])

# Navigate to next page
if page.has_next:
    next_page = client.hr.employees.list(page=page.page + 1, page_size=50)

Automatic Iteration

Use list_all() to iterate over all pages automatically:

for page in client.hr.employees.list_all(page_size=100):
    for employee in page.data:
        print(employee["email"])

This yields one PageResponse per page and stops when there are no more pages.

Filtering with Pagination

You can combine pagination with filters:

# Paginated + filtered
page = client.trade.customers.list(
    page=1,
    page_size=20,
    status="active",
)

# Iterate all with filters
for page in client.trade.customers.list_all(page_size=50, status="active"):
    for customer in page.data:
        print(customer["name"])

Collecting All Results

To collect all items into a single list:

all_employees = []
for page in client.hr.employees.list_all(page_size=100):
    all_employees.extend(page.data)

print(f"Total collected: {len(all_employees)}")

Performance Tips

1. Use reasonable page sizes -- 25 to 100 items per page is optimal
2. Filter server-side -- pass filters to reduce the number of results
3. Avoid collecting everything -- process items as you iterate when possible
4. Use list() for known pages -- avoid list_all() if you only need the first page