# Multi-Page Responses

Some ShipStation API endpoints return paged results. This keeps response sizes manageable and prevents accidental over-fetching.

Examples of paginated endpoints include:

* [List Shipments](/apis/shipengine/docs/reference/list-shipments)
* [List Labels](/apis/shipengine/docs/reference/list-labels)
* [List Batches](/apis/shipengine/docs/reference/list-batches)
* [List Batch Errors](/apis/shipengine/docs/reference/list-batch-errors)


## Pagination Options

All paginated endpoints support the following fields, though the default values and allowed values may differ for each endpoint:

| Query Parameter | Type | Description |
|  --- | --- | --- |
| `page` | integer | Which page of results you want. Defaults to 1. |
| `page_size` | integer | The number of resources returned per page. The default varies by endpoint, as does the max value. |
| `sort_dir` | `asc` or `desc` | The sort order of results. Defaults to `desc` for most endpoints. |
| `sort_by` | enumerated string | Which field to sort by. The default value and available values differ by endpoint. |


## Pagination Fields

Paginated responses include several fields to help you determine the total number of pages, which page you're on, and how to request other pages.

| Field Name | Type | Description |
|  --- | --- | --- |
| `total` | integer | The total number of resources that match your search criteria. |
| `page` | integer | The current page of results. |
| `pages` | integer | The total number of pages. |
| `links` | object | URLs of the first, last, previous, and next pages of results. |


## Example Request & Response


```http
  GET /v1/shipments?page_size=25&sort_dir=desc&sort_by=created_at HTTP/1.1
  Host: api.shipengine.com
  API-Key: __YOUR_API_KEY_HERE__
```

**Response**


```json
 {
   "shipments": [],
   "total": 168,
   "page": 1,
   "pages": 7,
   "links": {
     "first": {
       "href": "https://api.shipengine.com/v1/shipments?sort_dir=desc&sort_by=created_at&page=1&page_size=25"
     },
     "last": {
       "href": "https://api.shipengine.com/v1/shipments?sort_dir=desc&sort_by=created_at&page=7&page_size=25"
     },
     "prev": {},
     "next": {
       "href": "https://api.shipengine.com/v1/shipments?sort_dir=desc&sort_by=created_at&page=2&page_size=25"
     }
   }
 }
```