---
title: "List tracked containers"
method: GET
path: "/v1/containers"
---

# List tracked containers

`GET /v1/containers`

## Request

- Base URL: `https://api.trackingmcp.com`
- URL: `https://api.trackingmcp.com/v1/containers`
- Auth: HTTP bearer

## Query parameters

- `status` string
- `limit` integer
- `cursor` string
- `tags` string
- `archived` boolean

## Response `200`

Page of tracked containers.

- object
  - `ok` true, required
  - `api_version` string: The response contract this build answers, as a date. Pin it in your client.
  - `data` ContainerPage, required: The payload. Everything an endpoint returns sits under this key.
    - `items` object[]: The list of results.
      - `id` string: Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number.
      - `org_id` string: Your organisation. Every keyed read is scoped to it, so this is always your own id: it exists so a record stays self-describing once exported.
      - `identifier` string: The container number, bill of lading or booking this record tracks.
      - `identifier_type` string: What the identifier is. The keyed surface uses container_id, bill_of_lading or booking; the public tracker returns booking_number for the third.
      - `carrier_code` string: Carrier SCAC.
      - `carrier_name` string: Carrier name.
      - `tags` unknown[]: Your own labels on this box. Filter the list endpoint with them.
        - unknown
      - `status` string: Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered.
      - `eta` string: Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one.
      - `eta_is_estimated` boolean: True when the ETA is still a forecast, false when it is the actual arrival, null when there is no ETA at all. Never read a date alone as a promise.
      - `planned_departure_at` string: Departure the carrier planned or actually filed for the load port. Null when the carrier publishes none.
      - `current_vessel_imo` string: IMO of the hull carrying the box now. Null before loading and after discharge.
      - `poll_priority` string: Which polling cadence this box sits in (pre_departure, transit, arrival, dwell). It decides how often we ask the carrier, and moves on its own as the shipment progresses.
      - `demurrage_at_risk` boolean: True when the free-time clock on this box is a concern.
      - `demurrage_accrued_usd` number, nullable: Demurrage charged so far on this box, US dollars. Null when no rate applies, which is not the same as zero owed.
      - `demurrage_last_free_day` string, nullable: The last day before demurrage accrues, or null when no terms are on file.
      - `customs_hold_reason` string, nullable: Why customs is holding the box, when the carrier names a reason. Null when there is no hold.
      - `customs_hold_since` string, nullable: When the hold started. Null when there is no hold.
      - `origin_unlocode` string: Origin port UN/LOCODE, or null when the carrier named no origin we could resolve.
      - `destination_unlocode` string: Destination port UN/LOCODE, or null when unresolved.
      - `destination_name` string: Destination port name, falling back to its UN/LOCODE.
      - `container_size` string, nullable: Equipment size, for example 40HC. Null when the carrier did not state it.
      - `equipment_type` string, nullable: Equipment family as the carrier names it. Null when unstated.
      - `iso_type_code` string, nullable: The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer). Null when unstated.
      - `equipment_owner` string, nullable: Registered owner of the box, resolved from its BIC prefix. Null when the prefix is unregistered.
      - `equipment_lessor` string, nullable: Leasing company, when the box is leased rather than carrier-owned. Null otherwise.
      - `lessee_name` string, nullable: Who holds the box on lease. Null unless the lessor publishes it.
      - `carrier_hint_code` string, nullable: An unconfirmed carrier candidate derived from lessor data. Never a confirmed carrier: read carrier_code for that.
      - `lessor_status` string, nullable: The box status as the lessor reports it, for example on-hire or off-hire. Null when we hold no lessor record.
      - `lessor_checked_at` string, nullable: When we last asked the lessor. Null when we never have.
      - `connector_status` string, nullable: Where a request to connect this carrier stands, when the line needs one. Null when the carrier is already connected.
      - `connector_notify_requested_at` string, nullable: When you asked to be told the connector went live. Null when you did not ask.
      - `redelivery_reference` string, nullable: Redelivery booking for the empty. Null until one exists.
      - `redelivery_date` string, nullable: When the empty is due back. Null until scheduled.
      - `redelivery_location` string, nullable: Where the empty is due back. Null until scheduled.
      - `redelivery_yard` string, nullable: The depot the empty is due back at. Null until scheduled.
      - `lessor_contract_number` string, nullable: Lease contract the box sits on. Null unless published.
      - `lessor_contract_type` string, nullable: Lease type, for example long-term or one-way. Null unless published.
      - `equipment_manufacturer` string, nullable: Who built the box. Null unless the lessor publishes it.
      - `last_polled_at` string: When we last asked the carrier (ISO 8601).
      - `added_at` string: When you started tracking this box (ISO 8601).
      - `archived_at` string, nullable: When tracking stopped, or null while the box is still active.
      - `archived_reason` string, nullable: Why tracking stopped: your delete call, or an automatic close-out once the box finished its cycle. Null while active.
      - `unresolvable_since` string, nullable: When we gave up resolving this reference. Null while we are still trying, which is the normal state.
      - `unresolved_reason` string, nullable: Why a reference could not be resolved: invalid_number, not_found or bl_booking_unresolved. Null means resolved or still resolving.
      - `route_alert` string, nullable: A route problem we detected, for example a destination change or a missed connection. Null when the route is behaving.
      - `source` string: Where the answer on this call came from: direct_carrier or warm_db.
      - `delay_bars` string[]: Days late at each of the five voyage stages. Positive is late, negative is early, null means we cannot tell.
      - `route_ports` string, nullable: The ports on the route, in order.
      - `is_demo` boolean: True on a sample reference. Sample boxes return typical data and have no live carrier feed.
      - `vessel_position` object: Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet.
        - `imo` string: IMO number of the vessel.
        - `name` string: Human-readable name.
        - `lat` number: Latitude.
        - `lng` number: Longitude.
        - `speed_knots` integer: Speed over ground, in knots.
        - `heading_deg` integer: Heading in degrees.
        - `nav_status` string: Navigational status as reported by AIS, for example "Under way using engine" or "Moored". We drop a moored or anchored claim that the position contradicts.
        - `position_updated_at` string: When we last wrote the position row.
        - `position_fix_at` string: When the hull was actually observed. This, not position_updated_at, is the age that matters.
        - `position_age_hours` number: How old the fix is, in hours.
        - `position_freshness` string: live, recent, stale, outdated, or unknown when we hold no usable fix.
      - `carrier_notice` CarrierNotice, nullable: Latest reference-specific reply from the named carrier. SHIPMENT_CANCELLED is an explicit matched Maersk cancellation, independent of retained movement history. no_longer_available is Swire stating it no longer serves tracking details for this shipment. ZIM notices clear after useful tracking.
        - `carrier_code` 'ZIMU' | 'MAEU' | 'CHVW'
        - `reference` string
        - `reference_type` 'container' | 'bl' | 'booking'
        - `status` 'other_carrier' | 'temporarily_unavailable' | 'not_found' | 'invalid_reference' | 'SHIPMENT_CANCELLED' | 'no_longer_available'
        - `message` string
        - `checked_at` string, date-time
        - `suggested_carrier` string, nullable
        - `suggested_url` string, uri, nullable
      - `carrier_document_reply` CarrierDocumentReply, nullable: Latest retained, exact-reference OOCL document reply. Separate from shipment event history; does not imply a fresh carrier check.
        - `carrier_code` 'OOLU'
        - `reference` string
        - `reference_type` 'bl' | 'booking'
        - `status` 'cancelled' | 'declined'
        - `carrier_reference` string
      - `line_suggestion` object, nullable: Another line that answered this container directly, shown when the line you named has no record of it. A hint only: the line on the shipment stays yours. To track it there, add the reference again with this carrier_code.
        - `carrier_code` string
        - `carrier_name` string, nullable
        - `found_at` string, date-time
    - `has_more` boolean: True when another page is waiting behind next_cursor.
    - `next_cursor` string: Cursor for the next page, or null when there are no more.

## Other responses

- `401`: Missing or invalid API key.

---

[API](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api.md) · [All operations](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api/revisions/6bb8d8172ceb?raw)