Pagination
Page through REST API lists with the page and pageSize parameters, and use the total and hasNext fields of the response to read every page.
List operations return their results one page at a time. You choose the page and its size with query parameters, and the response tells you how many items there are and whether more pages follow.
Parameters
Most list operations take these parameters:
| Parameter | Type | Default | Allowed values |
|---|---|---|---|
page | integer | 1 | 1 or more. Pages are numbered from 1. |
pageSize | integer | 50 | 1–200 items per page. |
A value outside these ranges returns 422 Unprocessable Entity with the code VALIDATION_FAILED. A few list operations use other limits; the API reference lists them. Many list operations also accept filters and sorting parameters, such as q for a text search. The API reference lists the parameters of each operation.
Response format
{
"data": [
{ "id": "3e1f0c9a8b7d4e6f9a2b1c0d8e7f6a5b", "name": "data-01" }
],
"meta": {
"page": 1,
"pageSize": 50,
"total": 128,
"hasNext": true
}
}| Field | Meaning |
|---|---|
data | The items on this page. The example shortens each item. |
meta.page | The number of this page. |
meta.pageSize | The page size that applied to this request. |
meta.total | The number of items on all pages together. |
meta.hasNext | true when more items follow this page, that is, when page × pageSize is less than total. |
A few list operations return all their items at once, as { "data": [...] } without meta, and take no paging parameters. For example, the list of a project's open volume transfers works this way.
Read every page
Request pages with increasing page numbers until meta.hasNext is false:
page=1
while :; do
resp=$(curl -s "https://<api-host>/api/v1/scopes/<project-id>/storage/volumes?page=$page&pageSize=200" \
-H "Authorization: Bearer $PC_TOKEN")
echo "$resp" | jq -c '.data[]'
[ "$(echo "$resp" | jq -r '.meta.hasNext')" = "true" ] || break
page=$((page + 1))
done<api-host>: the host name of the API.<project-id>: the ID of the project.
Pages are computed when you request them, by position in the list. If items are created or deleted while you read the pages, an item can move to a neighboring page, so you can miss it or read it twice. To get a consistent view, read the pages in quick succession, and use the IDs of the items to remove duplicates.