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

# Shipment and Container Filter Reference

> Exact public list filter names, values, operators, combination rules, and limitations for shipments and containers.

Use these filters on `GET /shipments` and `GET /containers`. The SDK accepts the same canonical names without the `filter[...]` wrapper. Read [filter usage](/docs/api-docs/in-depth-guides/filtering-shipments-and-containers) for complete request examples and [SDK filtering](/docs/sdk/filtering-pagination) for TypeScript examples.

## Composition and values

Examples are synthetic or illustrative values. Replace dynamic identifiers and names with values from authorized API results; syntactic validity does not guarantee existence in your account.

Different filter keys combine with **AND**. Within a key, scalar comma-separated values generally use **OR**; bracketed arrays generally use **AND**. Shipment `number`, port codes, owner IDs, terminal IDs, party IDs, and tags have the exceptions documented below. Never assume an array means OR for every field.

Date comparisons use `=`, `<`, `<=`, `>`, or `>=`. Encode a range as repeated bracketed array keys, such as `filter[pickup_lfd][]=FROM` and `filter[pickup_lfd][]=TO`, with comparison operators in the values where the filter supports them. Presence expressions are exactly `@exists` and `@not_exists`. Text search is supported by shipment `q`/`product` and container `search_by_*` filters; `~` on an exact string filter is invalid.

### Finite vocabularies

Container `current_status` values are `new`, `on_ship`, `available`, `not_available`, `grounded`, `on_rail`, `picked_up`, `off_dock`, `delivered`, `dropped`, `loaded`, `empty_returned`, `awaiting_inland_transfer`. Terms such as `in_transit`, `discharged`, and `available_for_pickup` are not current-status codes. Shipment `voyage_status` values are only `arrived` and `on_ship`.

Party roles are `shipper`, `consignee`, `notify_party`, `customs_broker`, `customer`, `freight_forwarder`, `pickup_dray_carrier`. Party match operators are `any` and `all`. Boolean filters use literal `true` and `false`; the SDK supplies their exact wire representation.

### Account-defined and lookup values

Port codes, terminal IDs, carrier SCACs, user/account/party IDs, tags, and product text are not finite universal enums. Use values from authorized API results. Port and terminal relationships can be loaded with [include](/docs/api-docs/in-depth-guides/including-resources); carrier codes come from [shipping lines](/docs/api-docs/api-reference/shipping-lines/shipping-lines); party IDs come from the parties associated with your account. User ownership IDs and creator account IDs are different identifiers. A random or inaccessible ID can return no matches. Supplying an ID never expands account access.

## Shipment filters

| API parameter | SDK field | Shape | Example | Semantics and restrictions |
| - | - | - | - | - |
| `filter[q]` | `q` | Search text | `"EXAMPLE_VALUE"` | Prefix text search across shipment numbers, reference numbers, and linked container identifiers. Use search text, not comparison expressions. |
| `filter[number]` | `number` | Exact string / OR array | `"TEST-BOL-1"` | Exact number match. Shipment arrays mean OR; container arrays of exact numbers mean AND. Use comma-separated container numbers for OR. Shipment scalar commas are literal. |
| `filter[created_at]` | `created_at` | Timestamp expression / bounds | `">=2026-10-01T00:00:00Z"` | Creation date. Use an ISO 8601 date-time with Z or a timezone offset; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Relative dates and comma-separated timestamps are not accepted. Use @exists or @not\_exists for presence. |
| `filter[actively_tracked]` | `actively_tracked` | Boolean | `true` | true selects shipments with tracking not stopped; false selects stopped tracking. Applies via the related shipment for containers. |
| `filter[tracking_stopped]` | `tracking_stopped` | Boolean | `true` | true selects stopped tracking; false selects tracking not stopped. Combines with other filters using AND. |
| `filter[voyage_status]` | `voyage_status` | arrived / on\_ship | `"on_ship"` | arrived means actual POD arrival is present; on\_ship means a voyage exists and actual POD arrival is absent. It is not a general shipment lifecycle status. |
| `filter[arriving_today]` | `arriving_today` | true selector | `true` | true selects shipments with POD or destination estimated/actual arrival today in the API server day. false does not narrow the list. The SDK accepts only true. |
| `filter[pod_ata_at]` | `pod_ata_at` | Date expression / bounds | `">=2026-10-01"` | Actual POD arrival date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pod_arrival]` | `pod_arrival` | Date expression / bounds | `">=2026-10-01"` | POD arrival date: actual arrival takes precedence over estimated arrival. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pod_code]` | `pod_code` | Exact string / CSV / array / presence | `"USLAX"` | Port of discharge UN/LOCODE. Use exact literals, comma-separated values, or arrays with OR semantics. Presence checks and comparison/search operators do not apply to this scope. |
| `filter[pod_eta_changed_at]` | `pod_eta_changed_at` | Timestamp expression / bounds | `">=2026-10-01T00:00:00Z"` | Meaningful change in the POD-local ETA date, comparing the current ETA with its historical baseline. Requires a lower ISO 8601 timestamp bound (=, >, or >=); an optional upper bound must be later. Applies only to active, unarrived shipments with an ETA. Not a raw updated\_at filter; a future lower bound is not guaranteed to produce no matches. |
| `filter[pod_terminal_id]` | `pod_terminal_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | Port of discharge terminal ID. Obtain it from the related terminal resource. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean OR for this shipment terminal filter. \~ is not supported. |
| `filter[pol_code]` | `pol_code` | Exact string / CSV / array / presence | `"CNSHA"` | Port of lading UN/LOCODE. Use exact literals, comma-separated values, or arrays with OR semantics. Presence checks and comparison/search operators do not apply to this scope. |
| `filter[owner_id]` | `owner_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | User ID associated with a shipment container. Accepts one ID, comma-separated IDs, or arrays with OR semantics. Use exact literals, comma-separated values, or arrays with OR semantics. Presence checks and comparison/search operators do not apply to this scope. |
| `filter[creator_id]` | `creator_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | Shipment creator account ID. Comma-separated IDs mean OR; arrays of distinct IDs mean AND and return no matches. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[customer_id]` | `customer_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | Customer account ID or customer party ID. Falls back to the shipment creator when no customer party role exists. Presence checks refer to the customer party role. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[product]` | `product` | Search text | `"EXAMPLE_VALUE"` | Prefix text search of an associated product name or SKU. |
| `filter[party_id]` | `party_id` | IDs / any-all object | `"00000000-0000-4000-8000-000000000001"` | Party ID match. Accepts a scalar, comma-separated IDs, an array (OR), or an object with value and operator (any or all). Values must come from parties visible to your account. |
| `filter[tags]` | `tags` | Tag names / array | `"EXAMPLE_VALUE"` | Account-scoped shipment tags. Comma-separated names or arrays match ANY tag by default. |
| `filter[tags_and]` | `tags_and` | Boolean | `true` | With tags, true requires ALL tags; false or absent means ANY. Has no effect without tags. The SDK requires tags (or shipment tag) when this modifier is supplied. |
| `filter[tag]` | `tag` | Tag names / array | `"EXAMPLE_VALUE"` | Alias for tags. When both are present, tag takes precedence. Uses the requesting account tag names. |

### Shipment aliases

Top-level `number`, `q`, and `tracking_stopped` are compatibility aliases; nested filters take precedence. Top-level `q` is deprecated, and a blank top-level `q` returns 400. No sunset date is documented. Shipment `number` is an exact shipment-number lookup, not a container-number search.

### Shipment combinations to avoid

* `actively_tracked=true` with `tracking_stopped=true`, or both false: contradictory tracking populations.
* `voyage_status=arrived` with `pod_ata_at=@not_exists`: arrived requires actual POD arrival.
* `voyage_status=on_ship` with `pod_ata_at=@exists`: on\_ship requires actual POD arrival to be absent.
* `pod_eta_changed_at` with stopped tracking or `voyage_status=arrived`: the ETA-change filter already selects active, unarrived voyages.
* `arriving_today` as a substitute for `pod_arrival`: arriving\_today also checks destination milestones.

The API generally returns no matches for contradictory scopes. The SDK rejects the proven contradictions above and malformed inputs before sending a request.

## Container filters

| API parameter | SDK field | Shape | Example | Semantics and restrictions |
| - | - | - | - | - |
| `filter[number]` | `number` | Exact string / CSV / array / presence | `"CAIU1234567"` | Exact number match. Shipment arrays mean OR; container arrays of exact numbers mean AND. Use comma-separated container numbers for OR. Shipment scalar commas are literal. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[pol]` | `pol` | Exact string / CSV / array / presence | `"EXAMPLE_VALUE"` | Port of lading name (including raw routing data when no port relationship exists). Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[pod]` | `pod` | Exact string / CSV / array / presence | `"EXAMPLE_VALUE"` | Port of discharge name (including raw routing data when no port relationship exists). Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[destination]` | `destination` | Exact string / CSV / array / presence | `"EXAMPLE_VALUE"` | Destination name, including raw routing data when no port relationship exists. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[pol_code]` | `pol_code` | Exact string / CSV / array / presence | `"CNSHA"` | Port of lading UN/LOCODE. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[pod_code]` | `pod_code` | Exact string / CSV / array / presence | `"USLAX"` | Port of discharge UN/LOCODE. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[destination_code]` | `destination_code` | Exact string / CSV / array / presence | `"USLAX"` | Destination UN/LOCODE. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[shipping_line_scac]` | `shipping_line_scac` | Exact string / CSV / array / presence | `"MAEU"` | Shipping line Standard Carrier Alpha Code (SCAC). Obtain valid values from GET /shipping\_lines; preserve their exact codes. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[customer_id]` | `customer_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | Customer account ID or customer party ID. Falls back to the shipment creator when no customer party role exists. Presence checks refer to the customer party role. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[customer_name]` | `customer_name` | Exact string / CSV / array / presence | `"EXAMPLE_VALUE"` | Exact, case-sensitive customer company name. Prefer customer\_id for names containing punctuation rejected by the string parser. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[vessel_name]` | `vessel_name` | Exact string / CSV / array / presence | `"EXAMPLE_VALUE"` | Exact vessel name. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[pod_terminal_id]` | `pod_terminal_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | Port of discharge terminal ID. Obtain it from the related terminal resource. Exact match by default; optional =, @exists, or @not\_exists. Comma-separated literals mean OR. Arrays mean AND unless the parameter description says otherwise. \~ is not supported. |
| `filter[current_status]` | `current_status` | Known status / CSV / presence | `"available"` | Container status. Known values: new, on\_ship, available, not\_available, grounded, on\_rail, picked\_up, off\_dock, delivered, dropped, loaded, empty\_returned, awaiting\_inland\_transfer. Unknown values return no matches in the API; the SDK rejects them. Comma-separated states mean OR; arrays mean AND. |
| `filter[has_fees]` | `has_fees` | Boolean | `true` | true requires nonempty terminal fees; false requires an explicitly empty terminal fee array. Unreported/null fees match neither branch. |
| `filter[has_demurrage_fees]` | `has_demurrage_fees` | Boolean | `true` | true requires a terminal demurrage fee; false selects terminal records without a demurrage fee. Missing terminal data can be excluded. |
| `filter[has_fees_or_holds]` | `has_fees_or_holds` | Boolean | `true` | true requires fees OR holds; false requires both arrays to be explicitly empty. Missing terminal data can be excluded. |
| `filter[requires_attention]` | `requires_attention` | Boolean | `true` | true selects attention-marked, overdue pickup, or approaching-LFD containers. false selects containers whose stored attention value is false or null; it is not the exact complement of true. |
| `filter[eta_changed_in_last_24h]` | `eta_changed_in_last_24h` | true selector | `true` | Selects containers with estimated-event changes in the last 24 hours. Both true and false apply the positive selector in the API. The SDK accepts only true. |
| `filter[eta_changed_in_past_3_days]` | `eta_changed_in_past_3_days` | true selector | `true` | Selects containers with estimated-event changes in the past three days. Both true and false apply the positive selector in the API. The SDK accepts only true. |
| `filter[has_holds]` | `has_holds` | Boolean | `true` | true requires nonempty terminal holds; false requires an explicitly empty holds array. Unreported/null holds match neither branch. |
| `filter[actively_tracked]` | `actively_tracked` | Boolean | `true` | true selects shipments with tracking not stopped; false selects stopped tracking. Applies via the related shipment for containers. |
| `filter[search_by_ids]` | `search_by_ids` | Search text | `"EXAMPLE_VALUE"` | Prefix text search of container and linked shipment identifiers. Optional \~ prefix is supported here. Do not use \~ on exact string filters. |
| `filter[search_by_number]` | `search_by_number` | Search text | `"EXAMPLE_VALUE"` | Prefix text search of container numbers. Optional \~ prefix is supported here. Do not use \~ on exact string filters. |
| `filter[search_by_shipment_number]` | `search_by_shipment_number` | Search text | `"EXAMPLE_VALUE"` | Prefix text search of shipment numbers. Optional \~ prefix is supported here. Do not use \~ on exact string filters. |
| `filter[search_by_shipment_ref_numbers]` | `search_by_shipment_ref_numbers` | Search text | `"EXAMPLE_VALUE"` | Prefix text search of shipment reference numbers. Optional \~ prefix is supported here. Do not use \~ on exact string filters. |
| `filter[search_by_ref_numbers]` | `search_by_ref_numbers` | Search text | `"EXAMPLE_VALUE"` | Prefix text search of container reference numbers. Optional \~ prefix is supported here. Do not use \~ on exact string filters. |
| `filter[search_by_owner_id]` | `search_by_owner_id` | Exact string / CSV / array / presence | `"00000000-0000-4000-8000-000000000001"` | User IDs associated with containers. Use one ID or comma-separated user IDs; bracketed arrays are not supported by this scope. Presence and search operators do not apply. |
| `filter[delivered_at]` | `delivered_at` | Date expression / bounds | `">=2026-10-01"` | Delivery date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pod_discharged_at]` | `pod_discharged_at` | Date expression / bounds | `">=2026-10-01"` | POD discharge date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pod_arrived_at]` | `pod_arrived_at` | Date expression / bounds | `">=2026-10-01"` | Container POD arrival date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pol_etd_at]` | `pol_etd_at` | Date expression / bounds | `">=2026-10-01"` | Estimated port of lading departure date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pol_atd_at]` | `pol_atd_at` | Date expression / bounds | `">=2026-10-01"` | Actual port of lading departure date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[empty_out_at]` | `empty_out_at` | Date expression / bounds | `">=2026-10-01"` | Empty equipment out date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pol_full_in_at]` | `pol_full_in_at` | Date expression / bounds | `">=2026-10-01"` | Full equipment in at port of lading date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pol_vessel_loaded_at]` | `pol_vessel_loaded_at` | Date expression / bounds | `">=2026-10-01"` | Vessel loading at port of lading date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pol_vessel_departed_at]` | `pol_vessel_departed_at` | Date expression / bounds | `">=2026-10-01"` | Vessel departure at port of lading date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[arrival]` | `arrival` | Date expression / bounds | `">=2026-10-01"` | POD arrival date: actual arrival takes precedence over estimated arrival. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[picked_up_at]` | `picked_up_at` | Date expression / bounds | `">=2026-10-01"` | Pickup date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[empty_returned_at]` | `empty_returned_at` | Date expression / bounds | `">=2026-10-01"` | Empty return date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[created_at]` | `created_at` | Date expression / bounds | `">=2026-10-01"` | Creation date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[updated_at]` | `updated_at` | Date expression / bounds | `">=2026-10-01"` | Last record update date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[last_free_day_on][]` | `last_free_day_on` | Two-date range | `["2026-10-01","2026-10-07"]` | Inclusive two-date range, encoded as filter\[last\_free\_day\_on]\[]=FROM and filter\[last\_free\_day\_on]\[]=TO, without operators. Requires both dates. Also restricts to available/not\_available/off\_dock containers, tracking not stopped, and destination absent or the same as POD. Use pickup\_lfd for general comparisons. |
| `filter[inland_destination_rail_unloaded_at]` | `inland_destination_rail_unloaded_at` | Date expression / bounds | `">=2026-10-01"` | Inland rail unloading date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[final_destination_full_out_at]` | `final_destination_full_out_at` | Date expression / bounds | `">=2026-10-01"` | Final destination full out date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[inland_destination_eta_at]` | `inland_destination_eta_at` | Date expression / bounds | `">=2026-10-01"` | Estimated inland destination arrival date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[inland_destination_ata_at]` | `inland_destination_ata_at` | Date expression / bounds | `">=2026-10-01"` | Actual inland destination arrival date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pod_rail_departed_at]` | `pod_rail_departed_at` | Date expression / bounds | `">=2026-10-01"` | Rail departure from POD date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pickup_lfd]` | `pickup_lfd` | Date expression / bounds | `">=2026-10-01"` | Pickup last free day (LFD) date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pickup_lfd_rail_on]` | `pickup_lfd_rail_on` | Date expression / bounds | `">=2026-10-01"` | Reported rail pickup LFD date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pickup_lfd_terminal_on]` | `pickup_lfd_terminal_on` | Date expression / bounds | `">=2026-10-01"` | Reported terminal pickup LFD date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pickup_lfd_line_on]` | `pickup_lfd_line_on` | Date expression / bounds | `">=2026-10-01"` | Reported shipping-line pickup LFD date. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pickup_lfd_terminal_effective_on]` | `pickup_lfd_terminal_effective_on` | Date expression / bounds | `">=2026-10-01"` | Terminal pickup LFD. Calculated values are used only when enabled and visible for the account/carrier; otherwise reported values are used. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[pickup_lfd_line_effective_on]` | `pickup_lfd_line_effective_on` | Date expression / bounds | `">=2026-10-01"` | Shipping-line pickup LFD. Calculated values are used only when enabled and visible for the account/carrier; otherwise reported values are used. Use YYYY-MM-DD or today/N.days.ago/N.days.from\_now; prefix with =, \<, \<=, >, or >=. Arrays combine bounds with AND. Comma-separated dates mean OR. Use @exists or @not\_exists for presence. Compares the stored date component, not timestamp instants; no automatic conversion to the port timezone is applied. |
| `filter[tags]` | `tags` | Tag names / array | `"EXAMPLE_VALUE"` | Account-scoped shipment tags. Comma-separated names or arrays match ANY tag by default. |
| `filter[tags_and]` | `tags_and` | Boolean | `true` | With tags, true requires ALL tags; false or absent means ANY. Has no effect without tags. The SDK requires tags (or shipment tag) when this modifier is supplied. |
| `filter[parties]` | `parties` | Role-to-IDs object | `{"shipper":"00000000-0000-4000-8000-000000000001"}` | Filter by account-visible party IDs or presence, grouped by role. IDs within a role use OR; different roles use AND. pickup\_dray\_carrier checks only the container role; other roles check container or shipment roles. Unknown roles are ignored by the API and rejected by the SDK. |

### Missing data and selectors

`has_holds=false` means an explicitly empty terminal holds array; it does not mean “no reported hold information.” Likewise, fee selectors can exclude containers without terminal data. Do not infer total account coverage by adding true and false counts. `requires_attention=false` is not the exact complement of true because true also checks deadline and pickup predicates.

The API treats `eta_changed_in_last_24h=false` and `eta_changed_in_past_3_days=false` as positive selectors. It treats shipment `arriving_today=false` as a no-op. Omit these filters to disable them; the SDK accepts only true. Relative dates and “today” use the API's server day, while ETA-change comparisons evaluate meaningful changes to the POD-local ETA date.

### Currently unavailable container filters

The following controller-defined inputs did not provide usable filtering in authenticated deployed checks on 2026-10-05. They are excluded from the supported SDK/OpenAPI filter catalog pending API verification or correction.

| Input | Observed limitation | Alternative |
| - | - | - |
| `filter[pod_eta_at]` | Valid date and presence requests returned HTTP 500. | Use shipment POD-date filters; use container `arrival` when actual-or-estimated arrival is appropriate. |
| `filter[pod_ata_at]` | Valid date and presence requests returned HTTP 500. | Use shipment `pod_ata_at`, or container `pod_arrived_at` when the container arrival milestone is appropriate. |
| `filter[custom_fields][API_SLUG]` | Known account-defined slugs left results unfiltered in the verification account. | Read custom fields from authorized responses; do not claim a list has been scoped by this input. |

These alternatives have different milestone semantics; choose the one matching the question. The SDK produces an actionable ValidationError for the unavailable inputs.

## Sorting and pagination

Sorting and `include` change order/response shape; they do not scope the collection. Shipment default order is newest creation first. Container default order is most recent status refresh first. Container pages cap at 50; larger API requests are truncated. Shipment requests use the SDK's conservative page-size cap of 100. Use page numbers starting at 1.

The SDK list methods return one page. Use `links.next` or a bounded iterator to continue. `meta.total` is the filtered collection total; it is not the number of rows fetched. Mark a row-based answer partial while more pages remain, and preserve every filter across subsequent pages.

Unknown API filter keys and unknown party roles are ignored rather than rejected. The SDK rejects unknown keys/roles and unsupported sort tokens to prevent account-wide results from being mistaken for a scoped answer. Never treat an HTTP 200 response alone as proof that a filter applied.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.