Pagination

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:

{
  "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	20	No maximum
GET /v1/external-accounts	10	No maximum
GET /v1/external-accounts/institutions	10	No maximum
GET /v1/cards and GET /v1/cards/applications	10	No maximum
GET /v1/wallets	10	100
GET /v1/transactions	10	No maximum
GET /v1/fx/orders	20	100
GET /v1/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 and 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 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.

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	At most the 10 newest matching rows. Use the transactions list for a full day
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