# 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
curl -X GET \
  https://api.astrada.co/subaccounts?limit=10 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...'
```

### Response

```json
{
  "_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
curl -X GET \
  https://api.astrada.co/cards?offset=10&limit=10 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...'
```

### Response

```json
{
  "_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.