---
title: "Look up a tracked container by its identifier"
method: GET
path: "/v1/containers/lookup/{identifier}"
---

# Look up a tracked container by its identifier

`GET /v1/containers/lookup/{identifier}`

## Request

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

## Path parameters

- `identifier` string, required

## Response `200`

Container detail.

- object
  - `ok` true, required
  - `api_version` string: The response contract this build answers, as a date. Pin it in your client.
  - `data` ContainerLookup, required: The payload. Everything an endpoint returns sits under this key.
    - `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.
    - `container_number` string: The container number, or null when the record was tracked by a bill of lading or booking that has not yet resolved to a box.
    - `bl_number` string, nullable: The bill of lading, or null when the record was not tracked by one.
    - `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.
    - `booking_number` string, nullable: The booking reference, or null when the record was not tracked by one.
    - `container_size` string: Equipment size, for example 40HC. Null when the carrier did not state it.
    - `equipment_type` string: Equipment family as the carrier names it. Null when unstated.
    - `iso_type_code` string: The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer). Null when unstated.
    - `child_containers` string, nullable: The boxes a bill of lading or booking resolves to, each with its own timeline. Null on a plain container lookup.
    - `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.
    - `carrier` string: Carrier name, falling back to the SCAC when we hold no name.
    - `vessel_name` string: Name of the carrying vessel, or null when the carrier named none.
    - `vessel_imo` string: IMO number of the carrying vessel, or null when unknown.
    - `planned_vessel` object, nullable: The ship the box is waiting for: before its first actual load while its planned load at the port of loading is still ahead or at most 3 days past, or at a transshipment hub before the reload. An object with name, imo, voyage, position (lat, lng, updated_at; that vessel's own latest AIS fix, null when older than 48 hours or when the planned load date passed more than 3 days ago with no actual load), heading_to (unlocode, name of the port it loads the box at), planned_load_at and status 'planned'. Never the box's position, which stays at the port. Null while the box is aboard, after its final discharge, or when the line names no planned vessel.
    - `vessel_position` object: Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet.
      - `lat` number: Latitude.
      - `lng` number: Longitude.
    - `origin_name` string: Origin port name, falling back to its UN/LOCODE.
    - `destination_name` string: Destination port name, falling back to its UN/LOCODE.
    - `eta` string: Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one.
    - `eta_confidence_pct` integer: How often this lane arrives on time, as a percentage. Null on a lane too thin to score.
    - `last_updated_at` string: The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment.
    - `last_updated_source` string: Which of the two produced last_updated_at: carrier_poll or ais_vessel_position. Null when neither has happened yet.
    - `last_polled_at` string: When we last asked the carrier (ISO 8601).
    - `last_ais_fix_at` string: When the vessel was last actually observed by AIS, or null when we hold no fix.
    - `field_provenance` object: Per-field account of WHY a declared field is empty, keyed by field name. This is the difference between "the carrier does not publish it", "your contract terms would unlock it" and "it does not apply to this shipment". Keys are data, not contract: they vary by shipment.
    - `demurrage_free_days_left` string, nullable: Days of free time left, or null when no terms are on file.
    - `ai_narrative` string, nullable: Reserved for a written summary of the shipment. Currently always null.
    - `events` object[]: Milestone timeline, oldest to newest.
      - `type` string: Event code, for example DEPA or LOAD.
      - `classifier` string: DCSA classifier: ACT for actual, EST for estimated, PLN for planned.
      - `is_actual` boolean: True when the event happened. False means planned or estimated.
      - `label` string: The event in plain words. A non-actual event is tagged "(planned)".
      - `timestamp` string: Event timestamp (ISO 8601).
      - `event_local_datetime` string: The port wall-clock for the same moment, naive and with no offset, exactly as a terminal prints it. Null when we could not place the port, and a null here means we do not know, never assume UTC.
      - `utc_offset_minutes` integer: Minutes to add to the UTC instant to reach the local wall-clock. Null with the local time.
      - `event_timezone` string: IANA zone of the port, which survives a DST change in a way a bare offset cannot. Null when the port could not be resolved.
      - `date_only` boolean: True when the carrier published a calendar date with no time of day. The instant then reads midnight UTC, which is padding, not an observed time: read `event_date` instead and do not convert it to another zone.
      - `event_date` string, nullable: The calendar date, YYYY-MM-DD, when `date_only` is true. Null for events that carry a real time of day.
      - `location` string: UN/LOCODE for the event, or null when the carrier gave no place.
      - `empty_indicator` string, nullable: EMPTY or LADEN, on equipment events. Null when the carrier did not report the fill state: the standard has no unknown value and we do not invent one, and this is not an end-of-shipment signal.
      - `empty_indicator_source` string: Who stated the fill state of an equipment event: carrier when the line reported EMPTY or LADEN, not_reported when it did not. Absent on vessel and document events, which have no fill state. We never fill the gap ourselves, so not_reported means the line did not say.
      - `gate_out_role` string: What a gate-out did, in the line's own words: transfer when the line says the box moved on (to another terminal, a rail ramp or a train), consignee_delivery when it says the consignee took the box, not_reported when it says neither. Only a consignee_delivery or an unstated gate-out at the destination can mark the box delivered. Present on gate-out (GTOT) events only.
      - `equipment_reference` string: The container the event happened to.
    - `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
    - `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

## Other responses

- `401`: Missing or invalid API key.
- `404`: Not in your tracking list.

---

[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)