Pagination · Compense Docs

Gateway lists come in one of two shapes:

Shape	Fields	Parameters	Where
`Page`	`count`, `results`, `next`, `previous`	`page`, `page_size`	Credit and subsidy queues, monetary allowance, PQRS, health (appointments, invoices, billing objections, schedule), administrative, webhook deliveries, loans
`OffsetPage`	`results`, `limit`, `offset`, `has_more`, `next_offset`	`limit`, `offset`	Wallet movements and bill payments

In every SDK a page is iterable over its results and keeps the original body in raw. What differs is how you request the next ones.

SDK	`Page`	`OffsetPage`	Auto-pagination
Python	`Page` (`count`, `results`, `next`)	`OffsetPage` (`has_more`, `next_offset`)	Your own loop with `page=` / `offset=`
JavaScript / TS	`Page`	`OffsetPage`	`for await (const x of page)`, `page.iterPages()`, `page.getNextPage()`
PHP	`Page` (`hasNext()`)	`OffsetPage` (`hasMore`, `nextOffset`)	`do … while` loop
.NET	`Page`	`OffsetPage`	`…AutoPagingAsync()` → `IAsyncEnumerable<JsonObject>`
Go	`*Page` (`HasNext()`)	`*OffsetPage` (`HasMore`, `NextOffset`)	`NewPageIterator` / `NewOffsetIterator` (and `it.All()` with Go 1.23+)

Iterating a list by page #

Example: every open, overdue PQRS at Caja Horizonte, 50 at a time.

page_no = 1
while True:
    page = client.pqrs.list(status="opened", overdue=True, page=page_no, page_size=50)
    for pqrs in page:
        escalate(pqrs)
    if not page.next:
        break
    page_no += 1

const first = await client.pqrs.list({ status: "opened", overdue: true, pageSize: 50 });
for await (const pqrs of first) {     // requests the following pages with the same filters
  await escalate(pqrs);
}

$n = 1;
do {
    $page = $client->pqrs->list(status: 'opened', overdue: true, page: $n++, pageSize: 50);
    foreach ($page as $pqrs) {
        escalate($pqrs);
    }
} while ($page->hasNext());

await foreach (var pqrs in client.Pqrs.ListAutoPagingAsync(status: "opened", overdue: true, pageSize: 50))
{
    await EscalateAsync(pqrs);
}

it := compense.NewPageIterator(ctx, func(ctx context.Context, page int) (*compense.Page, error) {
	return client.PQRS.List(ctx, &compense.PQRSListParams{
		Status: "opened", Overdue: compense.Bool(true), Page: page, PageSize: 50,
	})
})
for it.Next() {
	escalate(it.Item())
}
if err := it.Err(); err != nil {
	log.Fatal(err)
}

page=1
while :; do
  resp=$(curl -s "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/?status=opened&overdue=true&page=$page&page_size=50" \
    -H "X-API-Key: $COMPENSE_API_KEY")
  echo "$resp" | jq -c '.results[]'
  [ "$(echo "$resp" | jq -r '.next')" = "null" ] && break
  page=$((page + 1))
done

Iterating a list with limit/offset #

Example: all of a Nova user’s wallet movements for October.

offset = 0
while True:
    page = client.wallet.transactions.list("1032456789", start_date="2026-10-01",
                                           end_date="2026-10-31", limit=100, offset=offset)
    for movement in page:
        export(movement)
    if not page.has_more or page.next_offset is None:
        break
    offset = page.next_offset

const first = await client.wallet.transactions.list("1032456789", {
  startDate: "2026-10-01", endDate: "2026-10-31", limit: 100,
});
for await (const movement of first) {
  await exportMovement(movement);
}

$offset = null;
do {
    $page = $client->wallet->transactions->list('1032456789', startDate: '2026-10-01',
        endDate: '2026-10-31', limit: 100, offset: $offset);
    foreach ($page as $movement) {
        export_movement($movement);
    }
    $offset = $page->nextOffset;
} while ($page->hasMore && $offset !== null);

await foreach (var movement in client.Wallet.Transactions.ListAutoPagingAsync(
    "1032456789", startDate: "2026-10-01", endDate: "2026-10-31", limit: 100))
{
    await ExportAsync(movement);
}

it := compense.NewOffsetIterator(ctx, func(ctx context.Context, offset int) (*compense.OffsetPage, error) {
	return client.Wallet.Transactions.List(ctx, "1032456789", &compense.WalletTransactionsParams{
		StartDate: "2026-10-01", EndDate: "2026-10-31", Limit: 100, Offset: offset,
	})
})
for item, err := range it.All() { // Go 1.23+; with 1.21 use it.Next() / it.Item()
	if err != nil {
		log.Fatal(err)
	}
	export(item)
}

offset=0
while :; do
  resp=$(curl -s "https://sandbox.dev.compense.co/gw/v1/gateway/wallet/transactions/?document=1032456789&start_date=2026-10-01&end_date=2026-10-31&limit=100&offset=$offset" \
    -H "X-API-Key: $COMPENSE_API_KEY")
  echo "$resp" | jq -c '.results[]'
  [ "$(echo "$resp" | jq -r '.has_more')" = "true" ] || break
  offset=$(echo "$resp" | jq -r '.next_offset')
done

Caveats #

Page limits. page_size ranges from 1 to 100 (25 by default in most lists); limit from 1 to 100 (50 by default for movements). Asking for more doesn’t raise an error: it’s capped.
Auto-pagination follows next. The JS, .NET and Go iterators (and hasNext() in PHP) keep going while the response includes next. Some lists don’t include it (for example, the webhook delivery history returns count, page and page_size), and in that case auto-pagination stops at the first page. For those lists, advance yourself by comparing what you’ve received with count (example in webhook retries).
Lists that don’t paginate. Some operations return everything in a single page (for example, an affiliate’s credits and the administrative lists with no page parameter): there, hasNextPage()/HasNext() is false.
Data that changes while you iterate. If records are created during iteration, a page can repeat or skip items. For complete exports, filter by a closed date range and deduplicate by id.