> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How list endpoints return a page, and how to walk to the next one.

List endpoints return one page at a time, newest first, and tell you whether more exist. Pages move
by a cursor, not by an offset, so a record created while you are walking never shifts the pages
under you.

| Parameter        | Meaning                                                                         |
| ---------------- | ------------------------------------------------------------------------------- |
| `limit`          | How many to return, 1 to 100. Defaults to 20                                    |
| `starting_after` | The `id` of the last record of the previous page; the page after it is returned |

Every page answers the same shape:

```json theme={null}
{
  "object": "list",
  "data": [{ "object": "payment", "id": "pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCd" }],
  "has_more": true
}
```

## Walking every page

Read `has_more`. While it is `true`, send the `id` of the last record in `data` as `starting_after`
and ask again. Stop when it is `false`.

```bash theme={null}
curl "https://api-dashboard.payra.com/v1/payments?limit=20" \
  -H "Authorization: Bearer sk_test_..."

curl "https://api-dashboard.payra.com/v1/payments?limit=20&starting_after=pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCd" \
  -H "Authorization: Bearer sk_test_..."
```

Because pages run newest first, a record created after you start walking sorts ahead of the first
page: it never shifts the pages you are reading, and you never see a record twice. A payment or refund
is ordered by when its request began, so one whose request was still running when you started can
land in a page you already read.

## Cursors are scoped to your workspace

`starting_after` must be the `id` of a record from that same list, in your workspace and the same environment as
the key you are sending. Anything else is `400 parameter_invalid` naming `starting_after`, whether the id belongs to
another workspace, to the other environment, or to nothing at all. The three read the same on
purpose, so a cursor cannot be used to probe for ids that are not yours.