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

# List and search Shipments

> Search your Shipments with filters, AND/OR conditions, and cursor pagination.

`GET /v5/shipment/list/` searches your Shipments and returns each match's key information plus its latest event. For a single Shipment's full record, use [Retrieve Shipment Details](/guides/retrieve-shipment). All parameters: [API reference](/api-reference/v5/shipments/list-shipments).

## The date range is required

Every request must include **exactly one** of these pairs — they cannot be combined:

* `created_date_from` + `created_date_to`
* `updated_date_from` + `updated_date_to`
* `latest_event_date_from` + `latest_event_date_to`

Rules: both ends together, `_from` ≤ `_to`, format `yyyy-mm-ddThh:mm:ss` (processed as UTC), and `_from` at most **13 months** in the past — Perform.AI's search retention window.

```bash theme={null}
curl --request GET \
  --url 'https://api.perform.ai/v5/shipment/list/?created_date_from=2026-09-01T00:00:00&created_date_to=2026-09-19T23:59:59&status=active&limit=50' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

## Filters and AND/OR conditions

Filters include identifiers and references, `carrier_id` / `carrier_reference`, `status`, `current_phase`, `tags`, notification contacts, `from_country_code` / `to_country_code`, `issue_state`, `issue_types`, and `shipping_type` — the reference lists them all with their limits.

Most filters accept **AND/OR bracket syntax**. String values must be quoted, and one bracket level means AND while two mean OR:

| Goal                 | Syntax                                          |
| -------------------- | ----------------------------------------------- |
| Single value         | `carrier_reference=dhlexp`                      |
| AND — all must match | `carrier_reference=['dhlexp','fedex']`          |
| OR — any matches     | `carrier_reference=[['dhlexp','fedex']]`        |
| Mixed                | `carrier_reference=['usps',['dhlexp','fedex']]` |

<Warning>
  Unquoted string values inside brackets are not parsed — the filter is silently ignored. Depending on your HTTP client, URL-encode `[`, `]`, and `'`.
</Warning>

## Pagination

Pagination is cursor-based:

1. First request: `next_page=0` (or omit it). `limit` is 25–100, default 25.
2. Each response returns a `next_page` cursor — pass it into the next request unchanged.
3. **You're on the last page when the response no longer contains `next_page`.**

`total_result` reports the total match count on every page.

## Read the response

```json theme={null}
{
  "api_response": "200",
  "total_result": 2,
  "next_page": 510603416,
  "data": [
    {
      "shipment_uuid": "5b8ed503-20d2-46cf-8675-ce77a059f691",
      "shipment_id": "SHP-2026-000002",
      "tracking_number": "00340434616780000001",
      "carrier": "DHL eCommerce",
      "status": "active",
      "current_phase": { "name": "Out for delivery", "key": "G" },
      "created_date": "2026-09-19T03:26:29+00:00",
      "updated_date": "2026-09-19T05:12:04+00:00",
      "order": { "order_uuid": "a0144751-6530-4135-8d73-f258a28ba27d", "order_id": "ORD-2026-000114" },
      "latest_event": {
        "event": "Out for delivery",
        "date_time": "2026-09-19T11:10:00+08:00",
        "timezone": "Asia/Singapore",
        "location": { "place": "Singapore" }
      }
    }
  ]
}
```

<Note>
  **A valid search with zero matches returns HTTP 404** with `api_response` `"4041"` — not an empty array. Treat it as "no shipments matched", not as a failure. (Document, label, PUDO, and carrier-config listings behave differently and return 200 with empty `data`.)
</Note>

## Common validation failures

| Error message                                     | Cause                                       |
| ------------------------------------------------- | ------------------------------------------- |
| `created_date or updated_date range is required.` | No date-range pair provided.                |
| `Full date range is required.`                    | A `_from` without its `_to`, or vice versa. |
| `Provided date range is not supported.`           | `_from` is more than 13 months in the past. |
| `Invalid date range.`                             | `_from` is after `_to`.                     |
| `Invalid carrier_id.`                             | `carrier_id` isn't exactly 6 characters.    |
| `Invalid search_condition.`                       | Malformed AND/OR brackets.                  |

## Next steps

* Fetch full records with [Retrieve Shipment Details](/guides/retrieve-shipment).
* Replace polling loops with [webhooks](/guides/webhooks) — the list API is for search and reconciliation, not change detection.