Skip to main content

Pagination

List endpoints return paginated results.

Pagination provides stable iteration over large datasets and avoids issues with offset-based paging.

Request parameters​

ParameterTypeDefaultDescription
pageinteger1Page number (1-indexed)
limitinteger20Number of results to return (1–100)

Response format​

{
  "success": true,
  "data": [
    { "id": "inv_42", "invoiceNumber": "INV-0001", "total": 150000 },
    { "id": "inv_43", "invoiceNumber": "INV-0002", "total": 240000 },
    { "id": "inv_44", "invoiceNumber": "INV-0003", "total": 180000 }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

Response fields​

FieldDescription
dataArray of resources
meta.totalTotal number of matching resources
meta.pageCurrent page number
meta.limitResults per page
meta.hasMoreWhether additional results are available

Example: fetching invoices​

First page

curl "https://api.speybooks.com/v1/invoices?limit=20" \
  -H "Authorization: Bearer sk_live_your_api_key"

Response

{
  "success": true,
  "data": [...],
  "meta": {
    "total": 156,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

Next page

curl "https://api.speybooks.com/v1/invoices?page=2&limit=20" \
  -H "Authorization: Bearer sk_live_your_api_key"

Complete pagination example​

JavaScript

async function getAllInvoices(apiKey) {
  const invoices = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const url = new URL('https://api.speybooks.com/v1/invoices');
    url.searchParams.set('page', String(page));
    url.searchParams.set('limit', '100');

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    });

    const result = await response.json();

    if (result.success) {
      invoices.push(...result.data);
      hasMore = result.meta.hasMore;
      page++;
    } else {
      throw new Error(result.error.message);
    }
  }

  return invoices;
}

This pattern guarantees that each resource is processed exactly once.

Filtering with pagination​

Filters can be combined with pagination.

curl "https://api.speybooks.com/v1/invoices?status=sent&page=1&limit=50" \
  -H "Authorization: Bearer sk_live_your_api_key"

The total count in the response reflects the filtered dataset, not all resources.

Sorting with pagination​

Sorting can be applied when paginating.

# Newest first (default)
curl "https://api.speybooks.com/v1/invoices?sort=-createdAt" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Oldest first
curl "https://api.speybooks.com/v1/invoices?sort=createdAt" \
  -H "Authorization: Bearer sk_live_your_api_key"

Sorting order is respected consistently across pages.

Pagination behaviour​

  • Page numbers are 1-indexed
  • Results are ordered consistently within a query
  • New resources created during pagination may appear on subsequent pages
  • Deleted resources will not appear on subsequent pages

These guarantees ensure predictable iteration for automation and exports.

Key principles​

  • Page-based pagination with explicit totals
  • Stable ordering within a session
  • Deterministic iteration
  • Metadata always included

Pagination in SpeyBooks is designed to be safe for automation and large datasets.