---
title: "Pagination"
description: "How Gravv list routes page their results: the page and items_per_page family, limit and offset on v2 accounts, webhook history, and the lists that return everything at once."
---
Gravv list routes do not share one paging scheme. Most take `page` and `items_per_page`, the v2 account routes take `limit` and `offset`, webhook history takes `page` and `limit`, and a few lists return everything in one response. Defaults and maximums differ by route. The API usually changes an out-of-range value without an error rather than refusing it.

**Example.** You want every payee of one customer. You call `GET /v1/external-accounts?customer_id=<CUSTOMER_ID>&page=1&items_per_page=50` and get 50 items. You ask for `page=2`, then `page=3`, and stop at the first page that holds fewer than 50 items. You do not stop on `total_items`, because on this route it is approximate.

## Page and items per page

Most v1 lists take `page`, which starts at 1, and `items_per_page`. The response holds `items` and the paging fields beside them:

```json title="A page of results"
{
  "data": {
    "items": [],
    "page": 2,
    "items_per_page": 50,
    "total_items": 120,
    "total_pages": 3
  },
  "error": null
}
```

| List | Default page size | Largest page |
| :-- | :-- | :-- |
| [`GET /v1/customers`](/api-reference/customers/get-v1-customers) | 20 | No maximum |
| [`GET /v1/external-accounts`](/api-reference/external-accounts/get-v1-external-accounts) | 10 | No maximum |
| [`GET /v1/external-accounts/institutions`](/api-reference/external-accounts/get-v1-external-accounts-institutions) | 10 | No maximum |
| [`GET /v1/cards`](/api-reference/cards/get-v1-cards) and [`GET /v1/cards/applications`](/api-reference/cards/get-v1-cards-applications) | 10 | No maximum |
| [`GET /v1/wallets`](/api-reference/wallets/get-v1-wallets) | 10 | 100 |
| [`GET /v1/transactions`](/api-reference/transactions/get-v1-transactions) | 10 | No maximum |
| [`GET /v1/fx/orders`](/api-reference/fx/get-v1-fx-orders) | 20 | 100 |
| [`GET /v1/settlement-instructions`](/platform/settlement-instructions/manage-settlement-instructions) | 10 | No maximum |

- **The API lowers a value over the maximum instead of refusing it.** Read `items_per_page` from the response instead of assuming the size you asked for. A value of 0 or below, or one that is not a number, usually gives the default. On wallets, a value that is not a number returns `400`.
- **"No maximum" does not mean a large page is a good idea.** The API returns a page of any size you ask for, but a large page is slow. Page through instead, with 50 or 100 a page.
- **`items_per_page` in the response does not always mean the page size.** On `GET /v1/transactions` it is the number of items on this page. On `GET /v1/cards` it echoes the value you sent, even one that the API replaced with the default.
- **Totals can be approximate or missing.** On payees, `total_items` is approximate. On transactions, `total_items` is an overestimate when there are more pages, and `0` on an empty page.
- **Stop on a short page.** On every one of these routes, keep asking for the next page until a page holds fewer items than the page size, or none.
- The order is fixed. Customers, payees, wallets and transactions are newest first. Settlement instructions list the default instruction first, then the rest newest first.

## Limit and offset (v2 accounts)

[`GET /v2/accounts`](/api-reference/accounts-v2/get-v2-accounts) and [`GET /v2/accounts/applications`](/api-reference/accounts-v2/get-v2-accounts-applications) take `limit` and `offset`. `offset` is the number of items to skip, so the second page of 50 is `limit=50&offset=50`.

| List | Default | Largest page | Response |
| :-- | :-- | :-- | :-- |
| `GET /v2/accounts` | 50 | 200 | `items`, `page`, `items_per_page`, `total_items`, `total_pages` |
| `GET /v2/accounts/applications` | 50 | 200 | `applications`, `count`, `limit`, `offset` |

- A `limit` of 0 or below, or above 200, gives **50**, not 200. `limit=500` returns 50 items.
- A `limit` or `offset` that is not a number is a `400`.
- `GET /v2/accounts` also takes `page` and `items_per_page`. The API uses them only when you do not send `limit` and `offset`.
- The applications list has no total. `count` is the number of applications on this page. Ask for the next `offset` until `count` is less than `limit`.

## Webhook history

[`GET /v1/webhooks/history`](/api-reference/webhooks/get-v1-webhooks-history) takes `page`, starting at 1, and `limit`. `limit` is 50 by default, and the API lowers a value over 100 to 100. The response has the same fields as the `page` and `items_per_page` family. See [Webhooks](/platform/webhooks/webhooks-overview).

## Lists with no paging

These lists return a fixed set. Where they accept `page` and `items_per_page`, they ignore them.

| List | What it returns |
| :-- | :-- |
| [`GET /v1/transactions/export`](/api-reference/transactions/get-v1-transactions-export) | At most the 10 newest matching rows. Use the [transactions list](/recipes/transactions/reconcile-a-day-of-movements) for a full day |
| [`GET /v1/collections/cards`](/api-reference/collections/get-v1-collections-cards) | Every saved card of the customer, the default card first, then newest |
| A customer's KYC documents | Every document. An empty set is a `404`, not an empty list |
| Transfer rates, supported currencies and supported countries | The whole list |