Pagination

Overview

API endpoints that return collections (like listing payments) use pagination to limit response size and improve performance. Superbank uses offset-based pagination.

Pagination Parameters

Parameter	Type	Default	Description
`limit`	number	20	Number of items per page (max: 100)
`offset`	number	0	Number of items to skip

Request Example

curl -X GET "https://api-sandbox.superbank.com/v1/payments?limit=10&offset=20" \
  -H "X-Api-Key: your-api-key"

Response Format

Paginated responses include a pagination object with metadata:

{
  "data": [
    {
      "id": "pay_abc123",
      "type": "LIQUIDITY",
      "amount": 100.00,
      "status": "COMPLETED"
    },
    {
      "id": "pay_def456",
      "type": "LIQUIDITY",
      "amount": 250.00,
      "status": "PENDING"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 20,
    "has_more": true
  }
}

Pagination Object

Field	Type	Description
`total`	number	Total number of items matching the query
`limit`	number	Items per page (as requested)
`offset`	number	Current offset
`has_more`	boolean	Whether more items exist after this page

Iterating Through Pages

JavaScript Example

async function getAllPayments(apiKey) {
  const payments = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api-sandbox.superbank.com/v1/payments?limit=${limit}&offset=${offset}`,
      {
        headers: { 'X-Api-Key': apiKey },
      }
    );

    const result = await response.json();
    payments.push(...result.data);

    hasMore = result.pagination.has_more;
    offset += limit;
  }

  return payments;
}

Python Example

import requests

def get_all_payments(api_key):
    payments = []
    offset = 0
    limit = 100
    has_more = True

    while has_more:
        response = requests.get(
            f'https://api-sandbox.superbank.com/v1/payments',
            params={'limit': limit, 'offset': offset},
            headers={'X-Api-Key': api_key},
        )
        result = response.json()
        payments.extend(result['data'])

        has_more = result['pagination']['has_more']
        offset += limit

    return payments

Filtering with Pagination

You can combine pagination with filters:

# Get the second page of completed payments
curl -X GET "https://api-sandbox.superbank.com/v1/payments?status=COMPLETED&limit=20&offset=20" \
  -H "X-Api-Key: your-api-key"

The total count reflects filtered results, not all records.

Best Practices

Use Reasonable Page Sizes

Default (20) is good for displaying in UI
Use larger limits (100) for bulk operations
Avoid very small limits to reduce API calls

Handle Empty Results

const result = await response.json();

if (result.data.length === 0) {
  console.log('No items found');
  return;
}

Respect Rate Limits

When paginating through large datasets, add delays between requests to avoid hitting rate limits:

async function fetchAllWithDelay(apiKey) {
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const result = await fetchPage(apiKey, offset);
    // Process result...

    hasMore = result.pagination.has_more;
    offset += 100;

    // Add delay between pages
    if (hasMore) {
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  }
}

Endpoints with Pagination

Endpoint	Description
`GET /v1/payments`	List payments

Get Started

Overview

Request Example

Response Format

Iterating Through Pages

JavaScript Example

Python Example

Best Practices

Use Reasonable Page Sizes

Handle Empty Results

Respect Rate Limits

Next Steps

List Payments

Error Handling

Get Started

​Overview

​Pagination Parameters

​Request Example

​Response Format

​Pagination Object

​Iterating Through Pages

​JavaScript Example

​Python Example

​Filtering with Pagination

​Best Practices

​Use Reasonable Page Sizes

​Handle Empty Results

​Respect Rate Limits

​Endpoints with Pagination

​Next Steps

List Payments

Error Handling

Overview

Pagination Parameters

Request Example

Response Format

Pagination Object

Iterating Through Pages

JavaScript Example

Python Example

Filtering with Pagination

Best Practices

Use Reasonable Page Sizes

Handle Empty Results

Respect Rate Limits

Endpoints with Pagination

Next Steps