list_shipments or list_containers to narrow results before requesting details. Both tools return one page with a maximum of 25 rows. They validate filter names and values before calling the API.
Choose an endpoint and filter
Resolve a carrier name with
get_supported_shipping_lines and use its Standard Carrier Alpha Code (SCAC). Obtain terminal, user, customer, and party identifiers from authorized records or account data. Do not invent UUIDs or assume a name is an ID. The tools do not perform automatic identifier lookups.
Use common inputs or advanced filters
Common filters appear directly in each tool’s schema. The strictadvanced_filters object contains all confirmed filters for that endpoint. Its descriptions specify operators and valid values. The complete API filter reference covers both catalogs.
Supply a filter in one location. Repeating a filter at the top level and in advanced_filters is an error, even when the values match. Shipment tag and tags are aliases; supply only one. Put sort, pagination, and include options at the top level.
For example, call list_containers with these arguments to select actively tracked containers that are available at the Port of Discharge (POD) in Los Angeles and have reported holds:
list_shipments with a pair of bounds. These dates illustrate the query syntax:
Choose valid values and combinations
Containercurrent_status and shipment voyage_status are different vocabularies. The tool schemas enumerate their accepted values. Use voyage_status values arrived or on_ship for shipments. Container states include available, on_ship, on_rail, picked_up, and empty_returned; use the schema for the full list.
Date-only filters compare stored calendar dates. Shipment created_at and pod_eta_changed_at require timestamps with Z or a timezone offset. For a local-port date question, query overlapping dates and refine using returned timestamps and the port timezone. See date precision and combinations.
Omit a one-way selector to disable it. arriving_today, eta_changed_in_last_24h, and eta_changed_in_past_3_days accept only true. Missing terminal data is different from an explicitly empty hold or fee array. A false hold or fee filter does not include every container outside the true result.
Container pod_eta_at, pod_ata_at, and custom_fields filters remain unavailable because deployed API checks found errors or ineffective filtering. Reading custom-field values with detail tools is separate from filtering by them.
Unknown names, invalid status values, malformed dates, duplicate inputs, and provably contradictory combinations return errors. Correct the arguments before retrying.
Continue with the same query
Results includeitems, API links and meta when available, and factual _metadata about the request:
These fields are inside
_metadata. If has_more is true, request next_page with the same filters, sort, and include options. Use the API next link to identify the page when a numeric next_page is unavailable. Each call retrieves one page.
Report how many rows you retrieved and whether more pages remain. A page’s row count is not the total worklist size. Reaching the last page does not prove that earlier pages were retrieved, and records can change between calls. Refine the query or ask whether to continue if the requested answer would require many pages.