# List Shipments Since shipments power most of our services, we allow you to query and manage them. By querying shipments, you expose a paged service that allows you to use multiple filters. | Query Parameters | Type | Description | | --- | --- | --- | | `batch_id` | *string* | Please note when filtering by `batch_id`: If you filter by batch, the API will ignore `shipment_status`, `modified_at_start`, `modified_at_end`, `created_at_start`, `created_at_end`, and `tag`. The API assumes you are opening a batch to view what's in the batch queue and `batch_id` is the only relevant filter since there are no other filters when executing a batch operation. | | `tag` | *string* | | | `shipment_status` | *ennumerated string* | `pending`, `processing`, `label_purchased`, `cancelled` | | `modified_at_start` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `2019-07-25T15:24:46.657Z` | | `modified_at_end` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `2019-07-25T15:24:46.657Z` | | `created_at_start` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `2019-07-25T15:24:46.657Z` | | `created_at_end` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `2019-07-25T15:24:46.657Z` | | `page` | *integer* | defaults to 1 | | `page_size` | *integer* | defaults to 25 | | `sort_dir` | *ennumerated string* | `asc` or `desc` | | `sort_by` | *ennumerated string* | `modified_at`, `created_at` | ## Pagination Limits When listing shipments, there is a **maximum pagination offset of 10,000 results**. The pagination offset is calculated as `page × page_size`. If you attempt to request results beyond this offset, the API will return a `400 Bad Request` error. **Examples:** - If `page_size=1`, the maximum page you can request is `10,000` - If `page_size=25` (default), the maximum page you can request is `400` (400 × 25 = 10,000) - If `page_size=500`, the maximum page you can request is `20` (20 × 500 = 10,000) **Error Response Example:** ```json { "request_id": "f41e6bc1-69f0-4b09-b0ab-cd2a3e4f5678", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "invalid_field_value", "message": "Pagination offset exceeds the maximum allowed value of 10000. Please narrow your query using filters such as modified_at_start/modified_at_end.", "field_name": "page", "field_value": "20000" } ] } ``` **How to work around this limit:** If you encounter this pagination limit, **add filtering parameters** to narrow your results: - Use date range filters like `modified_at_start` and `modified_at_end` or `created_at_start` and `created_at_end` - Filter by `shipment_status`, `tag`, or `batch_id` Need Help? If you're having trouble working within this pagination limit or need assistance optimizing your shipment queries, please contact our [API Support team](https://www.shipstation.com/support/). ## Example Request & Response **GET /v1/shipments** In this example, we'll get a list of the last package we sent using the `east_warehouse` tag. ```http GET /v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at HTTP/1.1 Host: api.shipengine.com API-Key: __YOUR_API_KEY_HERE__ ``` **Response** ```json { "shipments": [ { "shipment_id": "se-2102034", "carrier_id": "", "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c", "ship_date": "2019-07-25T05:00:00.000Z", "created_at": "2019-07-25T15:24:46.657Z", "modified_at": "2019-07-25T15:24:46.657Z", "shipment_status": "pending", "ship_to": { "name": "Amanda Miller", "phone": "555-555-5555", "email": "recipient@example.com", "address_line1": "525 S Winchester Blvd", "city_locality": "San Jose", "state_province": "CA", "postal_code": "95128", "country_code": "US", "address_residential_indicator": "yes" }, "ship_from": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "email": "sender@example.com", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "return_to": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "advanced_options": { "bill_to_account": null, "bill_to_country_code": null, "bill_to_party": null, "bill_to_postal_code": null, "contains_alcohol": false, "custom_field1": null, "custom_field2": null, "custom_field3": null, "non_machinable": false, "saturday_delivery": false }, "insurance_provider": "", "tags": [ { "name": "east_warehouse" } ], "total_weight": { "value": 9.60, "units": "ounce" }, "packages": [ { "weight": { "value": 9.60, "units": "ounce" }, "dimensions": { "units": "inch", "length": 12.00, "width": 7.10, "height": 6.00 }, "insured_value": { "currency": "usd", "amount": 0.0 } } ] } ], "total": 1, "page": 1, "pages": 2, "links": { "first": { "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=1&page_size=1" }, "last": { "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1" }, "prev": {}, "next": { "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1" } } } ```