Pagination

All list endpoints in the Banklyze API return paginated results. This guide explains the query parameters, response format, and strategies for iterating through large datasets efficiently.

Query Parameters

Every list endpoint accepts the following pagination parameters:

Name	Type	Required	Description
page	integer	Default: 1	The page number to retrieve (1-indexed).
per_page	integer	Default: 25	Number of results per page. Minimum 1, maximum 100.

Paginated request

# Fetch page 2 with 50 results per page
curl -s \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Org-Id: $ORG_ID" \
  "https://api.banklyze.com/v1/deals?page=2&per_page=50"

Response Format

Paginated responses include a data array and a meta object with pagination details:

Paginated response

{
  "data": [
    { "id": 101, "business_name": "Acme Trucking LLC", "status": "ready" },
    { "id": 102, "business_name": "Best Bagels Inc", "status": "processing" }
  ],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

PaginationMeta Fields

Name	Type	Required	Description
page	integer	Required	Current page number.
per_page	integer	Required	Number of results per page.
total	integer	Required	Total number of matching records across all pages.
total_pages	integer	Required	Total number of pages available.

Iterating All Pages

To retrieve every record, iterate through pages until page exceeds total_pages. The Python SDK provides built-in auto-pagination so you never need to manage page counters manually.

#!/bin/bash
PAGE=1
PER_PAGE=100
TOTAL_PAGES=1

while [ "$PAGE" -le "$TOTAL_PAGES" ]; do
  RESPONSE=$(curl -s \
    -H "Authorization: Bearer $API_KEY" \
    -H "X-Org-Id: $ORG_ID" \
    "https://api.banklyze.com/v1/deals?page=$PAGE&per_page=$PER_PAGE")

  # Process current page
  echo "$RESPONSE" | jq '.data[]'

  # Update total_pages from response meta
  TOTAL_PAGES=$(echo "$RESPONSE" | jq '.meta.total_pages')
  PAGE=$((PAGE + 1))
done

SDK Auto-Pagination

The Python SDK's list() methods return a PageIterator that automatically fetches subsequent pages as you iterate. You can also access individual pages directly for manual control.

Python SDK pagination

from banklyze import BanklyzeClient

client = BanklyzeClient(api_key="sk_live_...", org_id=1)

# Auto-pagination — iterates through all pages automatically
for deal in client.deals.list(per_page=100):
    print(deal.business_name)

# Manual pagination
page = client.deals.list(page=1, per_page=25)
print(f"Page {page.meta.page} of {page.meta.total_pages}")
print(f"Showing {len(page.data)} of {page.meta.total} deals")

# Iterate to next page
if page.meta.page < page.meta.total_pages:
    next_page = client.deals.list(page=page.meta.page + 1, per_page=25)

Performance Tips

Use per_page=100 for bulk operations

Fewer HTTP round-trips means faster total throughput. The maximum page size is 100 records.

Filter before paginating

Use query parameters like status, q, and date ranges to reduce the result set before pagination.

Cache total_pages

The total_pages value rarely changes between sequential page fetches. Cache it from the first response to build progress indicators.

Avoid deep pagination

Requesting page 1000+ is expensive. If you need to process very large datasets, use date-range filters to partition your queries.

For real-time updates, consider using webhooks instead of polling list endpoints. See the Webhooks Guide for details.

Error Handling

Idempotency