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:

{
  "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). The value is not silently cut to the maximum.