Pagination

Pagination in API

Across our API, we provide endpoints that allow you to "list" core resources. We use cursor-based pagination and offset-based pagination. These are managed via the path parameters on the request.

As we are using Hypertext Language Application (HAL), although we have two distinct types of pagination, we encourage you to leverage the _links provided as part of the response to navigate through the requests.

Link key	Description
`self`	URI for the returned collection of resources.
`next`	URI for the next page. Not present when there are no more resources to paginate.
`first`	URI for the first page. Provides the first collection of resources available according to the filters applied.
`last`	URI for the last page. Provides the last collection of resources available according to the filters applied.
`prev`	URI for the previous page. Not present on the first response when starting pagination (no previous page).

A collection resource always provides the self and next links. The first, last, and prev links are only available on offset-based pagination.

Cursor-based Pagination

Parameter	Description
`cursor`	The cursor to use for pagination. It identifies your place on the list.
`limit`	Specifies a limit on the number of items to return. Allows values between 1 and 100.

Request

curl -X GET \
  https://api.astrada.co/subaccounts?limit=10 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...'

Response

{
  "_links": {
    "self": { "href": "/subaccounts" },
    "next": { "href": "/subaccounts?cursor=ZXhhbXBsZQ==" }
  },
  "_embedded": {
    "subaccounts": [\
      { ... },\
      { ... }
    ]
  }
}

Offset-based Pagination

Parameter	Description
`offset`	The offset of the first item returned in the collection. For the first request, no `offset` needs to be provided.
`limit`	Specifies a limit on the number of items to return. Allows values between 1 and 100.

Request

curl -X GET \
  https://api.astrada.co/cards?offset=10&limit=10 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...'

Response

{
  "_links": {
    "self": { "href": "/cards?offset=10&limit=10" },
    "prev": { "href": "/cards?limit=10" },
    "next": { "href": "/cards?offset=20&limit=10" },
    "first": { "href": "/cards?limit=10" },
    "last": { "href": "/cards?offset=900&limit=10" }
  },
  "_embedded": {
    "cards": [\
      { ... },\
      { ... }
    ]
  },
  "totalItems": 30
}

Note: offset-based pagination returns totalItems as part of the response body with the total amount of resources matching the search criteria.