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 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 API 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 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 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

curl -iX GET https://api.shipengine.com/v1/shipments?page_size=25&sort_dir=desc&sort_by=created_at \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__'
  • curl

Example Response

{
  "shipments": [
    //
    // Current page of results here
    //
  ],
  "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"
    }
  }
}