# Pagination

> List endpoints return a page of objects, newest first, with a cursor for the next page.

Source: https://docs.borga.is/api/pagination

List endpoints return objects in reverse chronological order and accept two paging parameters:

**Query parameters**

- `limit` (integer, default 25): Page size, 1 to 100. Values out of range fall back to the default or the maximum.
- `starting_after` (string): The id of the last object on the previous page. The response starts with the object after it.

The response is an envelope with the page and a flag for whether more exists:

```json Response
{
  "data": [
    { "id": "pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6", "amount": 12900, "currency": "ISK", "status": "succeeded" },
    { "id": "pay_2Lm4Np6Qr8St0Uv2Wx4Yz6Ab", "amount": 1990, "currency": "ISK", "status": "succeeded" }
  ],
  "has_more": true
}
```

To walk a list, pass the last id back as `starting_after` until `has_more` is `false`.

```ts Node.js
// Walk every succeeded payment, 100 at a time.
let startingAfter: string | undefined;
do {
  const page = await borga.payments.list({
    status: "succeeded",
    limit: 100,
    starting_after: startingAfter,
  });
  for (const payment of page.data) {
    console.log(payment.id, payment.amount);
  }
  startingAfter = page.has_more ? page.data.at(-1)?.id : undefined;
} while (startingAfter);
```
```bash curl
curl "https://api.borga.is/v1/payments?status=succeeded&limit=100" \
  -H "Authorization: Bearer sk_test_…"

# Next page: pass the id of the last object you received.
curl "https://api.borga.is/v1/payments?status=succeeded&limit=100&starting_after=pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6" \
  -H "Authorization: Bearer sk_test_…"
```

An unknown or foreign `starting_after` id returns [`resource_missing`](/errors/resource_missing).

## Filters

Most lists accept filters as additional query parameters, for example `status` on payments or `customer` on subscriptions. They are listed on each resource page. Filters combine with paging.

## Endpoints without cursors

A few lists are bounded by nature and return at most `limit` objects with no `has_more`: refunds, credit notes and customer portals. Filter them by their parent (`payment`, `invoice`, `customer`) instead of paging.

There is no `ending_before` parameter and no total count.