shipengine-logo

Multi-Page Responses

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

Examples of paginated endpoints include:

Pagination Options

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

Query ParameterTypeDescription
pageintegerWhich page of results you want. Defaults to 1.
page_sizeintegerThe number of resources returned per page. The default varies by API endpoint, as does the max value.
sort_dirasc or descThe sort order of results. Defaults to desc for most endpoints.
sort_byenumerated stringWhich field to sort by. The default value and available values differ by API 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 NameTypeDescription
totalintegerThe total number of resources that match your search criteria
pageintegerThe current page of results
pagesintegerThe total number of pages
linksobjectURLs of the first, last, previous, and next pages of results

Example Request

1
2
3
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__

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
     "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"
       }
     }
   }