# Pagination

> Lists and filters return one page at a time. Read the pagination block, ask for the next page with page, and know which lists aren't paginated.

Web page: https://developer.yoprint.com/concepts/pagination/

Lists and filters return one page of records at a time, with a `pagination` block next to `data`:

```json
{
  "status": 200,
  "success": true,
  "data": [
    { "id": "V4keXwwxMQyXw7", "name": "Northwind Apparel" }
  ],
  "pagination": {
    "count": 50,
    "total": 128,
    "perPage": 50,
    "currentPage": 1,
    "totalPages": 3,
    "links": {
      "next": "https://secure.yoprint.com/v1/api/store/your-team/customer?page=2"
    }
  }
}
```

| Field         | Meaning                                                                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count`       | Records on this page.                                                                                                                                                               |
| `total`       | Records across all pages.                                                                                                                                                           |
| `perPage`     | The page size.                                                                                                                                                                      |
| `currentPage` | This page's number, from 1.                                                                                                                                                         |
| `totalPages`  | How many pages there are.                                                                                                                                                           |
| `links`       | `previous` and `next` URLs when they exist. With no other pages, `links` is an empty array `[]`, not an object, so handle both shapes if your client parses JSON with strict types. |

## Get the next page

Send `page` with the page number you want. On a `GET` list, put it in the query string:

```bash
curl "https://secure.yoprint.com/v1/api/store/your-team/customer?page=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1"
```

On a `POST` filter, put it in the body or the query string, and send the same filters again with each page:

```json
{
  "filters": [{ "key": "is_rush", "operator": "eq", "value": true }],
  "page": 2
}
```

A missing, invalid or `0` page number returns page 1.

> **Caution:** On a filter, the `links` URLs only add `?page=` to the filter's path. They don't carry your filters, so you can't just `GET` them. Send another `POST` with the next `page` instead.

## Read every page

Loop until `currentPage` equals `totalPages`:

```javascript
let page = 1;
let totalPages = 1;
const records = [];
do {
  const response = await fetch(`${base}/customer?page=${page}`, { headers });
  const body = await response.json();
  records.push(...body.data);
  totalPages = body.pagination.totalPages;
  page += 1;
} while (page <= totalPages);
```

Records can be added or changed while you page. For a stable list, sort by a field that doesn't change, such as when the record was created. See [Filtering and sorting](https://developer.yoprint.com/concepts/filtering-and-sorting.md).

## Page size

The page size is controlled by the `pagination_per_page` setting on the team (50 by default, configurable between 5 and 100). The team owner and members with the Manage Settings permission set it in the team's settings, or with `pagination_per_page`:

`PUT /v1/api/store/{team_slug}/setting/general` [Update general settings](https://developer.yoprint.com/reference/company-settings/v1-setting-general-update.md)

Callers cannot set page size per request: a `per_page` parameter is ignored on standard lists and filters. Read `perPage` from the `pagination` block rather than assuming a fixed size.

The job calendar is an exception. It accepts `per_page` in the query string up to 1,000, and returns 500 by default:

`POST /v1/api/store/{team_slug}/job/calendar` [List jobs in a date range](https://developer.yoprint.com/reference/jobs/v1-job-calendar.md)

The task calendar is different. It ignores `page` and `per_page`, returns at most 1,200 tasks, and never returns a `pagination` block:

`POST /v1/api/store/{team_slug}/work_pipeline/calendar` [List tasks in a date range](https://developer.yoprint.com/reference/tasks/v1-work-pipeline-calendar.md)

## Lists that aren't paginated

Some lists return every record at once, with no `pagination` block. They are lists inside one record, such as an order's jobs, invoices or shipments:

`GET /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/job` [List the jobs of a sales order or quote](https://developer.yoprint.com/reference/jobs/v2-job-index-for-order.md)

Order search returns at most 30 matches and isn't paginated. Narrow the search words to find a record that isn't in the first 30:

`GET /v2/api/store/{team_slug}/search/orders` [Search sales orders and quotes](https://developer.yoprint.com/reference/search/v2-search-orders-get.md)

## Count without reading

The v2 filters accept `"count_only": true`. The answer has the `pagination` block, with `total`, and no records.