> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How lists are paged in the HTS Pilot API - page and page_size on the paged lists, limit and offset on the others, and the shape of each answer.

Lists come in two forms. The larger ones are paged with `page` and `page_size` and answer with an object that
carries the total. The smaller ones take a `limit` and answer with a plain array. There are no cursors and no
`Link` headers.

## Paged lists

| Operation | `page_size` default | `page_size` maximum |
| --- | --- | --- |
| `GET /api/lookups` | 20 | 200 |
| `GET /api/review` | 20 | 200 |
| `GET /api/skus` | 50 | 500 |
| `GET /api/usage/ledger` | 25 | 200 |

| Parameter | Type | Meaning |
| --- | --- | --- |
| `page` | integer, from 1 | The page to return. Default 1 |
| `page_size` | integer | Items per page |

The answer:

```json
{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 20
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `items` | array | The objects of this page |
| `total` | integer | How many objects match the filters, on all pages |
| `page`, `page_size` | integer | What was asked for |

The SKU list adds `counts` (SKUs per code status) and the ledger adds `totals`. A page past the end answers `200`
with an empty `items` and the same `total`. To read everything, ask for `page` 1, 2, 3 and so on until
`page * page_size >= total`.

The lookup lists are ordered by `sort`: `newest` (the default), `oldest`, `confidence` (least certain first) or
`risk` (highest first). New lookups arrive while you page through a list ordered by `newest`, so an item can
appear on two pages; filter with `date_from` and `date_to`, or sort by `oldest`, when a complete pass matters.

## Lists with a limit

| Operation | Parameters | Default | Maximum | Answer |
| --- | --- | --- | --- | --- |
| `GET /api/batches` | `limit` | 20 | 100 | Array, newest first |
| `GET /api/batches/{batch_id}/rows` | `offset`, `limit` | 200 | 2000 | Array, in file order |
| `GET /api/alerts` | `limit` | 200 | 1000 | Array |
| `GET /api/datasets/{dataset_id}/entries` | `limit` | 50 | 500 | Array |
| `GET /api/hts/search` | `limit` | 50 | 200 | Object with `items` |
| `GET /api/tariff-changes` | `limit` | 200 | 2000 | Object with `items` |
| `GET /api/webhooks/{hook_id}/deliveries` | none | - | - | The last 50 deliveries |

These answers carry no total. For the rows of a batch, `total_rows` of the batch is the count, and `offset`
walks through them.

## Values outside the range

A `page` below 1, or a `page_size` or `limit` above its maximum, answers `422` with the field named in `errors`
([Errors](/errors.md#validation-errors)). The value is not silently cut to the maximum.