# Pagination, Filtering & Sorting

Source: https://docs.astalty.com.au/developers/api/pagination-filtering-and-sorting

> How list endpoints paginate results and how to filter and sort them.

Astalty Premium - This feature is part of the Astalty Premium plan. See What Premium includes.

## Overview

Endpoints that return a list of records, such as `GET /public/v1/participants`, return paginated results. Many list endpoints also accept filters or sorts. The available parameters differ by endpoint, so check the operation in the [API Reference](https://docs.astalty.com.au/developers/api-reference).

## Response shape

List responses wrap the records in a `data` array and include a `meta` object describing the current page:

```json
{
  "data": [
    { "id": "9ee9dc30-c869-4fb5-9871-b32850e68cad", "full_name": "Edd Romaguera" }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 94,
    "allowed_sorts": []
  }
}
```

- `current_page` and `last_page` show your position in the result set.
- `per_page` is the number of records returned on each page.
- `total` is the number of matching records.
- `allowed_sorts` lists the fields accepted by that endpoint's `sort` parameter. An empty array means that endpoint does not offer sorting.

## Pagination

Control paging with the `page` query parameters:

| Parameter      | Default | Notes                                                       |
| -------------- | ------- | ----------------------------------------------------------- |
| `page[number]` | `1`     | Page to return.                                             |
| `page[size]`   | `25`    | Records per page. Values are limited to the range 1 to 100. |

```bash
# Second page, 50 records per page
curl --globoff "https://api.app.astalty.com.au/public/v1/participants?page[number]=2&page[size]=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

To retrieve the full result set, increment `page[number]` until `meta.current_page` equals `meta.last_page`.

## Filtering

Narrow a list with `filter[...]` parameters. The [API Reference](https://docs.astalty.com.au/developers/api-reference) lists each endpoint's accepted filter names, values and comma-separated options.

```bash
# Active participants only
curl --globoff "https://api.app.astalty.com.au/public/v1/participants?filter[status]=active" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

## Sorting

Sort a list with the `sort` parameter and a field from `meta.allowed_sorts`. Prefix a field with a minus sign (`-`) for descending order. Some endpoints accept more than one comma-separated sort.

```bash
# Newest exports first
curl "https://api.app.astalty.com.au/public/v1/exports?sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```