Pagination

Overview

Every endpoint that returns a list of resources is paginated. A paginated response returns one page of results at a time, along with the links and counts needed to walk through the rest of them.

An endpoint is paginated if its response contains the links and meta objects described below. The API Reference lists the page and per_page query parameters on each of these endpoints.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	The page of results to return.
`per_page`	integer	`10`	The number of results to return on each page. Minimum `1`, maximum `5000`.

Both parameters are optional. Requesting a page beyond the last page returns an empty data array rather than an error.

GET /v3/accounts?page=2&per_page=50

Response Format

A paginated response wraps the results in data and adds links and meta:

{
  "data": [],
  "links": {
    "first": "https://api.aet.dev/api/v3/accounts?page=1",
    "last": "https://api.aet.dev/api/v3/accounts?page=12",
    "prev": null,
    "next": "https://api.aet.dev/api/v3/accounts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 10,
    "last_page": 12,
    "per_page": 10,
    "total": 118,
    "path": "https://api.aet.dev/api/v3/accounts",
    "links": []
  }
}

links

Field	Description
`first`	URL of the first page.
`last`	URL of the last page.
`prev`	URL of the previous page, or `null` on the first page.
`next`	URL of the next page, or `null` on the last page.

meta

Field	Description
`current_page`	The page number that was returned.
`from`	Index of the first result on this page within the full result set, or `null` when the page is empty.
`to`	Index of the last result on this page within the full result set, or `null` when the page is empty.
`last_page`	The number of the final page.
`per_page`	The page size that was applied.
`total`	Total number of results across every page.
`path`	Base URL of the endpoint, without the pagination query string.
`links`	Page links rendered for a paginator UI, each with a `url`, a `label`, and an `active` flag.

Working Through Every Page

Request the first page, then follow links.next until it is null. The links carry forward any other query parameters that were sent, such as filters and sorting, so they can be requested as-is.

Page boundaries are evaluated at request time. If records are created or deleted while paging through a list, a result can shift between pages and be seen twice or missed. When that matters, sort by a stable field or narrow the list with a filter before paging.

Prefer a larger per_page over many small requests when retrieving a full list, and keep in mind that a large page takes longer to return.