# Pagination and filtering

Lists come in two shapes. Small ones — tags, alert channels, certificates and the like — answer a plain JSON array
with everything in it. Lists that can grow large — domains, DNS zones, servers, monitors, incidents, maintenance
windows, contacts, watched domains, the audit log — are paginated. Each endpoint's [reference](reference.md) entry
shows which shape it answers, with a recorded example.

## Pages

Ask for a page with `page` (from 1) and its size with `per_page`:

```sh
curl "https://api.infranest.io/api/organizations/42/domains?page=2&per_page=100" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" \
  -H "Accept: application/json"
```

`per_page` is 25 by default and at most
200; a larger number is lowered to 200,
not refused. A few lists have their own sizes, which their reference entry states: the audit log takes up to 100,
a monitor's results up to 500.

A paginated answer puts the rows in `data`, with where you are beside them:

```json
{
  "current_page": 2,
  "data": [ { "id": 31, "domain": "example.com" } ],
  "first_page_url": "https://api.infranest.io/api/organizations/42/domains?per_page=100&page=1",
  "from": 101,
  "last_page": 3,
  "last_page_url": "https://api.infranest.io/api/organizations/42/domains?per_page=100&page=3",
  "next_page_url": "https://api.infranest.io/api/organizations/42/domains?per_page=100&page=3",
  "path": "https://api.infranest.io/api/organizations/42/domains",
  "per_page": 100,
  "prev_page_url": "https://api.infranest.io/api/organizations/42/domains?per_page=100&page=1",
  "to": 200,
  "total": 248,
  "links": [ { "url": null, "label": "« Previous", "page": null, "active": false } ],
  "meta": { "counts": { "total": 248, "expiring_soon": 3 } }
}
```

- **Walk the pages** by following `next_page_url` until it is `null`. It and the other `*_page_url` fields and
  `links` keep your filters, `sort`, `dir` and `per_page`, so you can follow them as they are. Asking for
  `page=1`, `2`, … yourself, with the same filters each time, works too.
- **`total`** counts every matching row, across all pages.
- **`meta`**, where a list has it, carries extra information about the list, such as `meta.counts`: the numbers
  behind the app's filter tabs.

There is no cursor. A row added while you walk the pages can shift the next page by one; for an exact copy, use the
[data export](/reference/data) instead.

## Filtering and searching

Filters are plain query parameters, named after what they filter, and each list documents its own. Most lists take:

| Parameter | What it does |
|---|---|
| `search` | Matches the obvious text fields, such as a name, a domain or an address. |
| `tag` | Only rows with this tag ID. |
| `status` | Only rows in this state; the values are listed on the endpoint. |

For example, domains that expire soon and will not renew by themselves:

```sh
curl "https://api.infranest.io/api/organizations/42/domains?expiring_soon=1&autorenew_off=1" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" \
  -H "Accept: application/json"
```

An unknown parameter is ignored rather than refused, so check the spelling against the reference when a filter seems
to do nothing.

## Sorting

Paginated lists sort with `sort` (a column the endpoint names) and `dir` (`asc` or `desc`). An unknown `sort` value is
ignored, and the list keeps its default order.

```sh
curl "https://api.infranest.io/api/organizations/42/domains?sort=expires&dir=asc" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" \
  -H "Accept: application/json"
```

## Times and dates

Times are ISO 8601 in UTC (`2026-01-15T09:30:00.000000Z`). Filters that take a date range, such as the audit log's `from`
and `to`, say on their entry whether they take a date or a time.