> ## 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 Shipments > Searches your Shipments and returns key information for each match, including its latest event. Use [Retrieve Shipment Details](#tag/Shipments) for the full record of a single Shipment. **A date range is required:** provide exactly one of the pairs `created_date_*`, `updated_date_*`, or `latest_event_date_*` — both ends together, `_from` ≤ `_to`, and `_from` at most **13 months** in the past (the data retention window). Format `yyyy-mm-ddThh:mm:ss`, processed as UTC. **AND/OR filters:** parameters marked *AND/OR* accept bracket syntax — `field=['a','b']` matches both (AND), `field=[['a','b']]` matches either (OR), `field=['x',['a','b']]` mixes them. String values must be quoted; URL-encode the brackets and quotes if your client requires it. **Pagination:** cursor-based. `limit` is 25–100 (default 25). Pass the `next_page` value from each response into the next request; the first page is `next_page=0`. You have reached the last page when the response no longer returns a `next_page` value. **No match:** a valid search with zero results returns **HTTP 404** with `api_response` `4041` — not an empty array. ## OpenAPI ````yaml /specs/public-api-v5.yaml get /v5/shipment/list/ openapi: 3.1.0 info: title: Perform.AI Public API (v5) version: 5.0.0 description: |- The Perform.AI Public API lets you create and manage shipments, returns, bookings, tracking events, and documents, and retrieve reference data such as PUDO locations and carrier configurations. All endpoints accept HTTPS connections only and are secured with OAuth 2.0. Generate a Bearer access token with your API credentials (Client ID and Client Secret, from **Integrations > API** in your account), then send it in the `Authorization` header of every request. This specification covers the following endpoints: - `POST /auth/oauth/token/` - `POST /v5/shipment/` - `POST /v5/shipment/update/` - `POST /v5-2-0/shipment/update/` - `GET /v5/shipment/list/` - `GET /v5/shipment/details/` - `GET /v5-2-0/shipment/details/` - `POST /v5/events/create/` - `POST /v5/return/` - `POST /v5/return/update/` - `GET /v5/shipments/documents/` - `GET /v5/shipments/documents/{document_uuid}/` - `GET /v5/shipments/documents/labels/` - `POST /v5/booking/` - `GET /v5/pudo-locations/` - `GET /v5/carrier-configs/` servers: - url: https://api.perform.ai security: - BearerAuth: [] tags: - name: Authentication description: Generate the Bearer access token used by every other endpoint. - name: Shipments description: Create, update, search, and retrieve Shipments. - name: Events description: Add manual tracking events to Shipments. - name: Returns description: Create and update Returns and their Return Shipments. - name: Documents description: Retrieve documents attached to Shipments. - name: Booking description: Book Open Shipments with carriers and provision shipping labels. - name: PUDO locations description: Search pick-up/drop-off locations across your configured carriers. - name: Carrier configurations description: Discover the carriers configured in your account. - name: Webhooks description: Shipment update payloads Perform.AI pushes to your endpoint. paths: /v5/shipment/list/: get: tags: - Shipments summary: List Shipments description: >- Searches your Shipments and returns key information for each match, including its latest event. Use [Retrieve Shipment Details](#tag/Shipments) for the full record of a single Shipment. **A date range is required:** provide exactly one of the pairs `created_date_*`, `updated_date_*`, or `latest_event_date_*` — both ends together, `_from` ≤ `_to`, and `_from` at most **13 months** in the past (the data retention window). Format `yyyy-mm-ddThh:mm:ss`, processed as UTC. **AND/OR filters:** parameters marked *AND/OR* accept bracket syntax — `field=['a','b']` matches both (AND), `field=[['a','b']]` matches either (OR), `field=['x',['a','b']]` mixes them. String values must be quoted; URL-encode the brackets and quotes if your client requires it. **Pagination:** cursor-based. `limit` is 25–100 (default 25). Pass the `next_page` value from each response into the next request; the first page is `next_page=0`. You have reached the last page when the response no longer returns a `next_page` value. **No match:** a valid search with zero results returns **HTTP 404** with `api_response` `4041` — not an empty array. operationId: get-v5-shipment-list parameters: - name: created_date_from in: query schema: type: string description: Start of the created-date range. Pair with `created_date_to`. - name: created_date_to in: query schema: type: string description: End of the created-date range. - name: updated_date_from in: query schema: type: string description: Start of the updated-date range. Pair with `updated_date_to`. - name: updated_date_to in: query schema: type: string description: End of the updated-date range. - name: latest_event_date_from in: query schema: type: string description: >- Start of the latest-event-date range. Pair with `latest_event_date_to`. - name: latest_event_date_to in: query schema: type: string description: End of the latest-event-date range. - name: tracking_number in: query schema: type: string description: Tracking number. Max 75 chars per entry. AND/OR. - name: shipment_reference in: query schema: type: string description: Shipment reference. Max 75 chars per entry. AND/OR. - name: additional_reference in: query schema: type: string description: Additional reference. Max 75 chars per entry. AND/OR. - name: order_uuid in: query schema: type: string description: Order UUID of the associated order. AND/OR. - name: order_id in: query schema: type: string description: Order ID of the associated order. Max 75 chars per entry. AND/OR. - name: order_reference in: query schema: type: string description: >- Order reference of the associated order. Max 75 chars per entry. AND/OR. - name: carrier_id in: query schema: type: string description: Perform.AI 6-character carrier ID. Exactly 6 characters. AND/OR. - name: carrier_reference in: query schema: type: string description: Configured carrier reference. Max 75 chars per entry. AND/OR. - name: status in: query schema: type: string enum: - pending - expired - active - inactive - delivered - return description: Shipment status. AND/OR. - name: current_phase in: query schema: type: string description: Current delivery phase, using standard phase keys. AND/OR. - name: tags in: query schema: type: string description: Tags added to the Shipment. AND/OR. - name: notification_email in: query schema: type: string description: Notification email address on the Shipment. AND/OR. - name: notification_phone in: query schema: type: string description: >- Notification phone number on the Shipment (normalized to `+{country code}{number}`). AND/OR. - name: tracking_page_reference in: query schema: type: string description: Tracking page reference. Max 150 chars per entry. AND/OR. - name: from_country_code in: query schema: type: string description: Origin country, ISO 3166-1 alpha-2. AND/OR. - name: to_country_code in: query schema: type: string description: Destination country, ISO 3166-1 alpha-2. AND/OR. - name: linked_shipments in: query schema: type: string description: >- Tracking number of a linked Shipment. Max 50 chars per entry. AND/OR. - name: issue_state in: query schema: type: string enum: - no_issue - current_issue - past_issue description: Whether the Shipment has, had, or never had an issue. AND/OR. - name: issue_types in: query schema: type: string description: Type of delivery issue encountered. AND/OR. - name: shipping_type in: query schema: type: string enum: - domestic - international description: Domestic or international. AND/OR. - name: limit in: query schema: type: integer minimum: 25 maximum: 100 default: 25 description: Results per response. - name: next_page in: query schema: type: integer default: 0 description: >- Pagination cursor. `0` for the first page; then the `next_page` value returned by the previous response. responses: '200': description: Matching Shipments. content: application/json: schema: $ref: '#/components/schemas/ListShipmentsResponse' example: 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 '400': description: |- Parameter validation failed. Causes include: `created_date or updated_date range is required.`, `Full date range is required.`, `Provided date range is not supported.` (older than 13 months), `Invalid date range.`, `Invalid carrier_id.`, `Invalid shipment_status.`, `Invalid phase_key.`, `Invalid issue_state.`, `Invalid shipping_type.`, `Invalid search_condition.`, `Exceeded character limit.`, `Invalid format.` content: application/json: schema: $ref: '#/components/schemas/FieldValidationError' example: api_response: '4030' message: validation_error errors: created_date_from: - created_date or updated_date range is required. created_date_to: - created_date or updated_date range is required. '403': $ref: '#/components/responses/Unauthorized' '404': description: The search was valid but no Shipments matched. content: application/json: schema: $ref: '#/components/schemas/RequestError' example: api_response: '4041' message: No results found with the provided search parameters '429': $ref: '#/components/responses/Throttled' '500': $ref: '#/components/responses/SystemError' components: schemas: ListShipmentsResponse: type: object properties: api_response: type: string total_result: type: integer description: Total number of Shipments matching the search. next_page: type: integer description: Cursor for the next page. Absent on the last page. data: type: array items: $ref: '#/components/schemas/ShipmentListItem' FieldValidationError: type: object description: >- HTTP 400 — one or more fields failed validation; nothing was persisted. For fields inside arrays, errors are keyed by the item's position as a string ("0", "1", …), then the field name. required: - api_response - message - errors properties: api_response: type: string description: Always `"4030"`. message: type: string description: Always `validation_error`. errors: type: object description: >- Affected field → array of error messages (or a nested object for array items). RequestError: type: object description: >- A request-level error such as `4000` (invalid request format), `4041` (no results found), or a `5XX` system error. required: - api_response - message properties: api_response: type: string description: Error code as a string, e.g. `"4000"`, `"4041"`, `"500"`. message: type: string ShipmentListItem: type: object properties: shipment_uuid: type: string format: uuid shipment_id: type: - string - 'null' tracking_number: type: - string - 'null' carrier: type: - string - 'null' description: Name of the carrier. status: type: string current_phase: $ref: '#/components/schemas/PhaseInfo' created_date: type: string updated_date: type: string order: type: object properties: order_uuid: type: - string - 'null' order_id: type: - string - 'null' latest_event: type: object properties: event: type: - string - 'null' date_time: type: - string - 'null' timezone: type: - string - 'null' location: type: object properties: place: type: - string - 'null' GatewayError: type: object description: >- An error generated at the API gateway — authorization (`403`) or throttling (`429`). Note `api_response` is a number here, unlike application-level responses where it is a string. required: - api_response - message properties: api_response: type: integer description: '`403` or `429`.' message: type: string description: E.g. `Key not authorized`, `Quota exceeded`, `Throttled`. PhaseInfo: type: object properties: name: type: - string - 'null' description: Name of the delivery phase. key: type: - string - 'null' description: Standard phase key. responses: Unauthorized: description: >- The Bearer token is expired, invalid, or missing — or the account lacks access. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: api_response: 403 message: Key not authorized Throttled: description: Rate limit exceeded (40 requests per second per account). content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: api_response: 429 message: Throttled SystemError: description: Internal system error. content: application/json: schema: $ref: '#/components/schemas/RequestError' example: api_response: '500' message: System error securitySchemes: BearerAuth: type: http scheme: bearer description: >- Used by every functional endpoint. Generate the token with `POST /auth/oauth/token/` and send it as `Authorization: Bearer {token}`. ````