> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primefreight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List shipments

> Retrieve a paginated list of shipment summaries.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.primefreight.com/v2/shipments?status=In%20Transit&limit=25" \
    -H "Authorization: Bearer <token>"
  ```
</RequestExample>

`GET /v2/shipments`

Returns a paginated list of shipment summaries, newest activity first. Use `updated_since` to poll for changes.

## Query parameters

<ParamField query="status" type="string">
  Filter by journey status. See [Status values](/api-reference/v2/status-values).
</ParamField>

<ParamField query="updated_since" type="string">
  Only shipments changed at or after this ISO 8601 time. Use it to poll for updates.
</ParamField>

<ParamField query="limit" default="25" type="integer">
  Page size, 1–100.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from the previous page's `next_cursor`.
</ParamField>

## Response

Each item in `data` is a shipment summary.

| Field                     | Type   | Description                                                          |
| ------------------------- | ------ | -------------------------------------------------------------------- |
| `id`                      | string | Shipment ID                                                          |
| `file_number`             | string | PrimeFreight file number                                             |
| `status`                  | string | Journey status. See [Status values](/api-reference/v2/status-values) |
| `customs_status`          | string | Customs status                                                       |
| `delivery_status`         | string | Delivery status                                                      |
| `eta_destination_revised` | string | Latest revised ETA at destination                                    |
| `container_id`            | string | ID of the container on this shipment                                 |
| `updated_at`              | string | When the shipment last changed                                       |

The envelope also returns `next_cursor` (string, or `null` on the last page) and `has_more` (boolean).

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "shp_100001",
        "file_number": "R00001",
        "status": "Departed Discharge Terminal",
        "customs_status": "Goods Not Yet Arrived",
        "delivery_status": "Goods Not Yet Arrived At Port",
        "eta_destination_revised": "2026-07-16T04:00:00-04:00",
        "container_id": "cnt_100001",
        "updated_at": "2026-07-16T05:12:44-04:00"
      },
      {
        "id": "shp_100002",
        "file_number": "R00002",
        "status": "Pre Alert",
        "customs_status": "Goods Not Yet Arrived",
        "delivery_status": "Goods Not Yet Arrived At Port",
        "eta_destination_revised": "2026-09-01T07:00:00-04:00",
        "container_id": "cnt_100002",
        "updated_at": "2026-07-14T09:03:11-04:00"
      }
    ],
    "next_cursor": "c_2b9f1a",
    "has_more": true
  }
  ```
</ResponseExample>