---
title: "Force update: ask the shipping line now and return the fresh detail"
method: POST
path: "/v1/containers/{id}/refresh"
---

# Force update: ask the shipping line now and return the fresh detail

`POST /v1/containers/{id}/refresh`

## Request

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

Asks the shipping line about this shipment now, bypassing our stored answer, and waits for it within a timeout (25 seconds by default). The response is the same detail GET /v1/containers/{id} returns, plus a `refresh` block saying what happened. When the line answered in time, `refresh.refreshed` is true, `refresh.from_cache` is false and `refresh.updated_at` is the time of that answer. When it did not, the detail is the last answer we hold, `refresh.from_cache` is true and `refresh.reason` says why (`line_timeout`, `line_no_answer`, `refresh_failed`); on a timeout the ask keeps running and `refresh.refreshing_in_background` is true, so a later GET serves its answer.

**Limit:** one force update per shipment per API key every 5 minutes (per signed-in user on the dashboard). The limit is shared with compat `force_update` for the same key and reference. Beyond it the answer is 429 with a `Retry-After` header and `error.retry_after` in seconds.

**Scope:** requires a `read_write` key, like every POST. A read-only key is refused with 403.

**Billing:** metered as one ordinary tracking call. It never counts the shipment a second time towards the unique-shipment allowance.

`{id}` is the container id, or a container, bill of lading or booking number the account tracks. An archived shipment is not refreshed (409): restore it first.

## Path parameters

- `id` string, required

## Response `200`

The detail, after asking the line, with the outcome in `refresh`.

- object
  - `ok` true, required
  - `api_version` string: The response contract this build answers, as a date. Pin it in your client.
  - `data` ContainerRecord, 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.
    - `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.
    - `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.
    - `booking_number` string, nullable: The booking reference, or null when the record was not tracked by one.
    - `carrier_code` string: Carrier SCAC.
    - `carrier_name` string: Carrier name.
    - `iso_code` string, nullable: ISO 6346 size and type code as the carrier filed it, for example 45G1. Null when the carrier stated none.
    - `size_teu` integer, nullable: Size in TEU: 1 for a 20ft box, 2 for a 40ft. Null when the size is unknown.
    - `container_type` string, nullable: Plain-language equipment type, for example Reefer or Dry. Null when the carrier stated none.
    - `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.
    - `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.
    - `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_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.
    - `eta_confidence_pct` integer: How often this lane arrives on time, as a percentage. Null on a lane too thin to score.
    - `discharge_datetime` string, nullable: When the box was discharged, which is when free time starts counting. Null when no discharge is on file yet.
    - `free_days` integer, nullable: Free days the terms allow at this port. Null when no terms and no published tariff apply.
    - `last_free_day` string, nullable: The last day free of charge, computed from the discharge and the free days. Null when either is missing.
    - `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.
    - `tags` unknown[]: Your own labels on this box. Filter the list endpoint with them.
      - unknown
    - `notes` string, nullable: Your own free-text note on this box. Null when you have written none.
    - `added_at` string: When you started tracking this box (ISO 8601).
    - `last_polled_at` string: When we last asked the carrier (ISO 8601).
    - `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.
    - `archived_at` string, nullable: When tracking stopped, or null while the box is still active.
    - `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.
    - `current_vessel_imo` string: IMO of the hull carrying the box now. Null before loading and after discharge.
    - `current_voyage_id` string, nullable: Carrier voyage number for the current leg. Null when the carrier publishes none.
    - `demurrage_daily_rate_usd` number, nullable: Daily demurrage rate in force at the destination, US dollars. Null when neither your terms nor a published tariff cover the port.
    - `demurrage_last_free_day` string, nullable: The last day before demurrage accrues, or null when no terms are on file.
    - `last_poll_trigger` string, nullable: What caused the most recent carrier check: a schedule, your recheck call, or a webhook. Null when the box has only ever been polled by the scheduler.
    - `tracker_lat` string, nullable: Latitude from a physical IoT tracker on the box, when you feed us one. Null on the great majority of boxes, which have no device.
    - `tracker_lng` string, nullable: Longitude from that device. Null with the latitude.
    - `tracker_updated_at` string, nullable: When the device last reported. Null when there is no device.
    - `tracker_has_alert` boolean: True when the device raised an alert, for example a door opening or a temperature excursion.
    - `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.
    - `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.
    - `unresolvable_since` string, nullable: When we gave up resolving this reference. Null while we are still trying, which is the normal state.
    - `route_alert` string, nullable: A route problem we detected, for example a destination change or a missed connection. Null when the route is behaving.
    - `planned_departure_at` string: Departure the carrier planned or actually filed for the load port. Null when the carrier publishes none.
    - `current_vessel_name` string: Name of that hull. Null when we hold no name for the IMO.
    - `cargo_cutoff_at` string, nullable: Cargo (gate) cutoff at the load port. Null when the carrier does not publish it, or when the ship has already sailed: read field_provenance to tell those apart.
    - `vgm_cutoff_at` string, nullable: VGM filing cutoff. Null under the same rules as cargo_cutoff_at.
    - `si_cutoff_at` string, nullable: Shipping-instruction cutoff. Null under the same rules as cargo_cutoff_at.
    - `customs_release_cutoff_at` string, nullable: Customs-release cutoff at the load port. Null under the same rules as cargo_cutoff_at.
    - `cutoff_enrichment` string, nullable: Where the cutoffs came from when they were not on the carrier response, for example a terminal schedule. Null when no enrichment ran.
    - `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.
    - `updated_at` string: When the record itself last changed in our database, which includes bookkeeping writes. For "when did we last learn something about the shipment", read last_updated_at.
    - `archived_reason` string, nullable: Why tracking stopped: your delete call, or an automatic close-out once the box finished its cycle. Null while active.
    - `identified_notified_at` string, nullable: Internal bookkeeping: when the "container identified" digest was sent for this box. Null when none was sent.
    - `intermediary_enriched_at` string, nullable: Internal bookkeeping: when a lessor or intermediary lookup last enriched this record. Null when none has run.
    - `import_batch_id` string, nullable: Groups every box created by one bulk import, so their digest fires once per batch. Null on a single manual add.
    - `seal_number` string, nullable: Carrier seal on the box. Null unless the carrier publishes it, which most do not on a track response.
    - `move_type` string, nullable: The scope of the move the carrier is performing, for example port to port or door to door. Null when unstated.
    - `vgm_kg` number, nullable: Verified gross mass, kilograms. Null until the shipper files a VGM and the carrier publishes it.
    - `gross_weight_kg` number, nullable: Gross weight of the loaded box, kilograms. Null when the carrier publishes none.
    - `package_count` integer, nullable: Pieces inside the box. Null when the carrier publishes no cargo particulars.
    - `package_unit` string, nullable: Unit the package count is in, for example CTN or PLT. Null with the count.
    - `measurement_cbm` number, nullable: Cargo volume, cubic metres. Null when the carrier publishes none.
    - `service_requirement` string, nullable: A special handling requirement filed on the shipment, for example a reefer set point. Null when none.
    - `commercial_raw` string, nullable: Cargo and commercial particulars exactly as the carrier filed them, when a carrier publishes any. Null on most lines. Read the typed fields above instead: this is kept so a value we did not map is never lost.
    - `tracked_from` string, nullable: The surface the box was added from. Null on records added before we recorded it.
    - `source` string: Where the answer on this call came from: direct_carrier or warm_db.
    - `route_data` object: The route in the shape our map consumers read: the legs, the current pin and the AIS block. Also returned on the compatibility surface, field for field.
      - `route` object[]: The legs of the drawn route. This is the map geometry, and it is not the four-point route block above.
        - `from` RoutePlace: Where the leg starts.
          - `lat` number: Latitude.
          - `lng` number: Longitude.
          - `name` string: Human-readable name.
          - `state` string: State, province or region of the port, when the gazetteer holds one.
          - `locode` string: UN/LOCODE of the place.
          - `country` string: Country name.
          - `timezone` string: IANA time zone of the place. Null when we could not resolve the port.
          - `country_code` string: ISO 3166-1 alpha-2 country code.
        - `to` RoutePlace: Where the leg starts.
          - `lat` number: Latitude.
          - `lng` number: Longitude.
          - `name` string: Human-readable name.
          - `state` string: State, province or region of the port, when the gazetteer holds one.
          - `locode` string: UN/LOCODE of the place.
          - `country` string: Country name.
          - `timezone` string: IANA time zone of the place. Null when we could not resolve the port.
          - `country_code` string: ISO 3166-1 alpha-2 country code.
        - `path` unknown[]: The drawn geometry of the leg as lat and lng pairs. Empty on an inland leg, where we do not draw a line we cannot verify.
          - unknown
        - `type` string: Event code, for example DEPA or LOAD.
        - `vessel` string, nullable: Vessel currently carrying the container, or null when we hold neither a name nor an IMO. Its lat and lng are always null here; the keyed endpoints carry the live position under vessel_position.
        - `transport_type` string, nullable: The mode carrying the leg, for example VESSEL or TRUCK, when the carrier names it. Null when it does not.
      - `pin` number[]: Where to draw the box right now, as a lat and lng pair. Null when we have nothing solid enough to place it.
      - `pin_source` string: How the pin was placed: ais_vessel_position from a real fix, route_reckoning when computed along the route, or a port when the box is sitting at one.
      - `ais` object: The vessel and port dates as an AIS-shaped block, kept in the layout integrators migrating from the older API already parse. Null when we hold no vessel.
        - `data` object: The AIS-shaped payload. It is nested under a data key because that is the layout of the API this surface is compatible with, not because it is a second envelope.
          - `vessel` object: The hull these dates belong to.
            - `imo` integer: IMO number of the vessel.
            - `flag` string: Flag state of the vessel, as a two-letter code. Null when we hold none.
            - `mmsi` integer: Vessel MMSI. Null when we hold none.
            - `name` string: Human-readable name.
            - `call_sign` string: Vessel radio call sign. Null when we hold none.
          - `last_event` object: The most recent vessel move behind these dates.
            - `date` string: When it happened, as a port wall-clock string without an offset, which is the layout this block has always used.
            - `voyage` string, nullable: Carrier voyage number, when published. Null otherwise.
            - `description` string: The carrier own phrasing for the event, falling back to our word for the code.
          - `updated_at` string: When this AIS block was last rebuilt.
          - `arrival_port` AisPortCall: The arrival call these dates describe.
            - `code` string: The short port code the compatible API prints next to the UN/LOCODE. Read locode for the standard one.
            - `locode` string: UN/LOCODE of the place.
            - `date` string: The date of the call, as a port wall-clock string with no offset, which is the layout this block has always used. Read date_label to know whether it is an estimate or an actual.
            - `date_label` string: Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual.
            - `country_code` string: ISO 3166-1 alpha-2 country code.
          - `departure_port` AisPortCall: The arrival call these dates describe.
            - `code` string: The short port code the compatible API prints next to the UN/LOCODE. Read locode for the standard one.
            - `locode` string: UN/LOCODE of the place.
            - `date` string: The date of the call, as a port wall-clock string with no offset, which is the layout this block has always used. Read date_label to know whether it is an estimate or an actual.
            - `date_label` string: Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual.
            - `country_code` string: ISO 3166-1 alpha-2 country code.
          - `discharge_port` object: The discharge call these dates describe.
            - `code` string: The short port code, as above. Read locode for the standard one.
            - `locode` string: UN/LOCODE of the place.
            - `date` string: The date of the sea discharge, in the same wall-clock layout. Read date_label before treating it as an actual.
            - `date_label` string: Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual.
            - `country_code` string: ISO 3166-1 alpha-2 country code.
            - `name` string: Human-readable name.
          - `last_vessel_position` object: The most recent fix for the hull, with the time it was taken.
            - `lat` number: Latitude.
            - `lng` number: Longitude.
            - `updated_at` string: When the fix was taken.
        - `status` string: Whether the AIS block carries data, and why not when it does not.
      - `source` object: Who produced the route and the AIS in this block. Read it before attributing our route to anybody else.
        - `provider` string: Machine name of the producer.
        - `provider_name` string: Display name of the producer.
        - `route_geometry` string: How the drawn line was produced, for example trackingmcp_computed.
        - `ais` string: Which vessel-position source fed the AIS block.
        - `note` string: One sentence of provenance in plain language.
      - `pin_estimated` boolean: True when the pin was computed rather than observed. Never present a computed pin as a sighting.
      - `pin_estimated_from` string, nullable: The observation the estimate was anchored to. Null when there was none to anchor to.
      - `geometry_version` integer: Which generation of our route-drawing produced this geometry. Bumped when the drawing changes, so a cached line can be invalidated.
    - `route_data_computed_at` string: When this route block was last built.
    - `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.
    - `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.
    - `lessor_on_hire_date` string, nullable: When the box went on hire. Null unless published.
    - `lessor_on_hire_location` string, nullable: Where it went on hire. Null unless published.
    - `lessor_on_hire_yard` string, nullable: The depot it went on hire at. Null unless published.
    - `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.
    - `connector_notified_at` string, nullable: When we told you it went live. Null when we have not.
    - `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.
    - `field_provenance_summary` object: Counts of the declared cutoff and demurrage fields by state, so you can tell "we do not have it" from "your contract terms would unlock it".
      - `resolved` integer: Declared fields we hold a value for.
      - `contract_required` integer: Declared fields that stay empty until you supply your own free-time terms.
      - `not_published` integer: Declared fields this carrier does not publish.
      - `not_applicable` integer: Declared fields that do not apply to this shipment.
      - `awaiting_carrier` integer: Declared fields we expect but have not received yet.
      - `unblocked_by_contract_terms` boolean: True when supplying free-time terms would fill at least one empty field.
    - `carrier_response_raw` string, nullable: The carrier payload behind this record, kept for support and replay. Null unless retention is on for your organisation. Not a stable shape: it is whatever that carrier sent.
    - `origin_coord` Coordinate: Coordinate of the origin port. Null when the port could not be placed.
      - `lat` number: Latitude.
      - `lng` number: Longitude.
      - `approximate` boolean: True when the coordinate is a place centroid rather than a terminal position. Do not measure distances against an approximate point.
      - `approx_from` string, nullable: What the approximate point was derived from. Null when the coordinate is exact.
    - `destination_coord` Coordinate: Coordinate of the origin port. Null when the port could not be placed.
      - `lat` number: Latitude.
      - `lng` number: Longitude.
      - `approximate` boolean: True when the coordinate is a place centroid rather than a terminal position. Do not measure distances against an approximate point.
      - `approx_from` string, nullable: What the approximate point was derived from. Null when the coordinate is exact.
    - `is_demo` boolean: True on a sample reference. Sample boxes return typical data and have no live carrier feed.
    - `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.
    - `ais_eta` string, nullable: Kept for older clients: the AIS-broadcast ETA, also present as vessel_position.eta_ais. Null when the hull broadcasts none.
    - `events` object[]: Milestone timeline, oldest to newest.
      - `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.
      - `container_id` string: The container number this row is about.
      - `dcsa_event_id` string: The id this event carries on the DCSA /v2 surface, so the same physical event can be matched across both surfaces.
      - `event_type` string: DCSA event category: SHIPMENT, TRANSPORT or EQUIPMENT.
      - `event_classifier_code` string: DCSA classifier: ACT, EST or PLN.
      - `event_date_time` string: When the event happened or is forecast to (ISO 8601).
      - `event_created_date_time` string: When we recorded the event, not when it happened. A late-filed event can be recorded days after the fact.
      - `transport_event_type_code` string, nullable: DCSA transport code on a vessel move: ARRI for arrival, DEPA for departure. Null on an equipment event.
      - `delay_reason_code` string, nullable: Carrier code for why a move slipped. Null on most lines, which publish no reason.
      - `change_remark` string, nullable: The carrier own free-text remark about a change to this event. Null when it sent none.
      - `equipment_event_type_code` string: DCSA equipment code on a box move, for example GTOT for a gate-out or LOAD for a load. Null on a transport event.
      - `empty_indicator_code` string: EMPTY or LADEN on an equipment event. Present only when the carrier reported the fill state: the standard has no unknown value and we do not invent one. It is not an end-of-shipment signal.
      - `equipment_reference` string: The container the event happened to.
      - `iso_equipment_code` string, nullable: ISO 6346 equipment code as filed on this event. Null when the carrier stated none.
      - `shipment_event_type_code` string, nullable: DCSA shipment code on a documentation move. Null on the other two families.
      - `document_id` string, nullable: The document the shipment event refers to, on the lines that publish one. Null otherwise.
      - `document_type_code` string, nullable: What that document is, for example a bill of lading. Null with the id.
      - `reason` string, nullable: The carrier stated reason for the event, on the lines that publish one. Null otherwise.
      - `transport_call` object: The location, vessel and voyage of the port call. Null when the carrier gave no call.
        - `location` object: UN/LOCODE for the event, or null when the carrier gave no place.
          - `locationName` string: Port name as the carrier wrote it, unmapped. Read the UN/LOCODE next to it for the resolved port.
          - `UNLocationCode` string: UN/LOCODE.
      - `references` string, nullable: Extra carrier references filed against the event. Null when the carrier filed none.
      - `seals` string, nullable: Seal numbers filed against the event. Null when the carrier filed none.
      - `normalisation_confidence` string: How sure we are of the normalised code: REPORTED when the carrier gave a code we map directly, INFERRED when we derived it from its wording, UNKNOWN when neither was possible.
      - `supplier_raw_event_code` string, nullable: The code the source used, before normalisation. Null when the source sent no code.
      - `supplier_raw_payload` string, nullable: The source own event object, kept verbatim. Null when nothing needed keeping. Not a stable shape.
      - `created_at` string: When the record was created (ISO 8601).
      - `event_id` string, nullable: The carrier own id for the event, when it publishes one. Null on most lines. Read id for our stable id.
      - `event_datetime` string: Same instant as event_date_time, under the name the earlier API used. Kept so old integrations keep working.
      - `event_code` string: Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA. Null when the carrier sent none.
      - `raw_payload` object: The connector event exactly as it was stored, so a value we did not map is never lost. Treat it as evidence, not as API surface: its keys vary by carrier.
        - `datetime` string: Event timestamp (ISO 8601), or null when the carrier gave none.
        - `timezone` string: IANA time zone of the place. Null when we could not resolve the port.
        - `unlocode` string: UN/LOCODE port code. On a tracking event it is canonicalised, and null when the carrier named no port.
        - `is_actual` boolean: True when the event happened. False means planned or estimated.
        - `port_name` string: Resolved port name.
        - `event_code` string: Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA. Null when the carrier sent none.
        - `vessel_imo` string, nullable: IMO number of the carrying vessel, or null when unknown.
        - `description` string: The carrier own phrasing for the event, falling back to our word for the code.
        - `source_kind` string: Which kind of source produced the event: carrier when the line answered directly; any other value means the event reached us another way.
        - `vessel_name` string, nullable: Name of the carrying vessel, or null when the carrier named none.
        - `event_family` string: Which family the code belongs to: EQUIPMENT, TRANSPORT or SHIPMENT.
        - `voyage_number` string, nullable: Carrier voyage number.
        - `datetime_basis` string: What the stored instant MEANS: utc for a true instant, port_local for a wall-clock we could not place. Every value on the documented fields above is already a true instant.
        - `datetime_local` string: The port wall-clock carried alongside the instant, inside the raw payload.
        - `time_semantics` string: How the instant was established during normalisation. Diagnostic, not contract.
        - `transport_mode` string, nullable: Mode the source named for the move. Null when it named none.
        - `datetime_precision` string: How precise the carrier was: datetime, or date when it gave a day with no time. A date-only event must never be read as midnight.
        - `utc_offset_minutes` integer: Minutes to add to the UTC instant to reach the local wall-clock. Null with the local time.
        - `source_resolve_method` string: The exact rung the source was resolved on, kept verbatim so a coarse bucket never hides the detail. Diagnostic.
      - `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.
      - `event_time_semantics` string: Internal marker for how this row timestamp was established. Do not branch on it: read the UTC instant and, if you need port time, its three local companions.
      - `event_name` string: The step in plain language, for example Gated out.
      - `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.
    - `journey_timeline` object[]: The shipment as a reader story: carrier events plus the moves we inferred between them, in order. Empty until the first event lands.
      - `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.
      - `kind` string: carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.
      - `classifier` string: DCSA classifier: ACT for actual, EST for estimated, PLN for planned.
      - `occurred_at` string: When the step happened (UTC). Null when the source gave a wall-clock we could not place.
      - `event_name` string: The step in plain language, for example Gated out.
      - `port_unlocode` string: Resolved port UN/LOCODE. Null when the carrier location could not be placed.
      - `port_name` string: Resolved port name.
      - `facility_name` string, nullable: Terminal or depot inside the port, when the carrier names one. Null otherwise.
      - `evidence_event_ids` string[]: The event ids this step was built from, so an inference can always be traced back.
      - `confidence` string: On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival.
      - `label` string: The event in plain words. A non-actual event is tagged "(planned)".
      - `port_role` string, nullable: The role the port plays on this route: origin, transshipment or destination. Null when the route is not resolved enough to say.
      - `milestone` string, nullable: The voyage milestone this step marks, when it marks one. Null on ordinary steps.
    - `exceptions` unknown[]: Count of shipments in an exception state: customs hold, rolled, delayed or at transshipment.
      - unknown
    - `history_days` integer: How far back the timeline reaches on your plan, in days.
    - `current_leg` string, nullable: The leg the box is on now. Null before departure and after final discharge.
    - `legs` unknown[]: The voyage broken into legs. Empty when we cannot yet split it.
      - 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.
      - `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.
      - `eta_ais` string: The destination ETA the vessel itself is broadcasting, which is the master own entry and often disagrees with the carrier. Null when the hull broadcasts none.
      - `destination_unlocode` string: Destination port UN/LOCODE, or null when unresolved.
      - `photo_url` string: Photograph of the hull. Null when we hold none.
      - `particulars_updated_at` string: When the vessel particulars were last refreshed.
      - `reported_nav_status` string: The navigational status the vessel broadcasts, unchecked.
      - `nav_status_verified` boolean: False when the broadcast status contradicts where the vessel actually is, for example Moored while far from any port. Then read nav_status, which we correct.
      - `nav_status_reason` string: Why the broadcast status was not trusted, for example outside_port_geofence. Null when it was trusted.
      - `nearest_port_nm` number: Distance to the nearest port, nautical miles, which is the evidence behind the check. Null when the status needed no checking.
    - `pin_source` string: How the pin was placed: ais_vessel_position from a real fix, route_reckoning when computed along the route, or a port when the box is sitting at one.
    - `pin_basis` string: What the reckoning leaned on when the pin was computed rather than observed, for example a published schedule.
    - `pin_estimated_from` string, nullable: The observation the estimate was anchored to. Null when there was none to anchor to.
    - `observed_position` object: The last position we actually observed, never a computed one. Null when the hull has no fix on record.
      - `lat` number: Latitude.
      - `lng` number: Longitude.
      - `observed_at` string: When the fix was taken.
      - `quality` string: How exact the fix is: precise for a terrestrial fix, coarse for a satellite one.
      - `accuracy_km` number, nullable: Radius the fix is good to, kilometres. Null when the source states no accuracy.
    - `estimated_position` object: A computed position, for when there is no fresh fix. Always labelled as computed; never merge the two blocks.
      - `lat` number: Latitude.
      - `lng` number: Longitude.
      - `estimated_at` string: The moment the estimate describes.
      - `based_on_observation_at` string, nullable: The observation the estimate was reckoned from. Null when the reckoning had no fix to start from and leaned on the schedule alone.
      - `classification` string: Which reckoning class produced the estimate. Diagnostic detail for support, not something to branch on.
      - `method` string: How the position was produced, for example route_reckoning.
    - `vessel_photo` object: Photograph of the current hull with its attribution. Null when we hold none.
      - `url` string: Where we POST the events.
      - `source` string: Where the answer on this call came from: direct_carrier or warm_db.
      - `retrieved_at` string: When we fetched the photograph.
    - `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_ais_fix_at` string: When the vessel was last actually observed by AIS, or null when we hold no fix.
    - `vessel_names` object: IMO to name map covering every leg, so an onward vessel can be named without a second call. Empty when no leg carries a hull we can name. Keys are data, not contract: they vary by shipment.
    - `transshipment` string, nullable: The hub the box is dwelling at and its onward vessel. Null unless it is dwelling.
    - `schedule_overlay` object: The published vessel rotation we matched this box to, which is the plan against which actuals can be read. Null when nothing matched.
      - `source` string: Where the answer on this call came from: direct_carrier or warm_db.
      - `match` string: How strongly the sailing matches the box, strongest first: vessel_voyage, vessel_lane, vessel_route, onward_vessel_lane, lane, carrier_lane. Weaker matches are context, not proof.
      - `carrier_code` string: Carrier SCAC.
      - `service_name` string: Carrier service or loop name.
      - `vessel_imo` string: IMO number of the carrying vessel, or null when unknown.
      - `voyage_number` string: Carrier voyage number.
      - `published_departure` string: The departure the carrier published (ISO 8601). Null when it published none.
      - `published_arrival` string: The arrival the carrier published (ISO 8601). Null when it published none.
      - `transit_days` integer: Port-to-port transit in days.
      - `is_transshipment` boolean: True when the box changes vessel on the way.
      - `legs` object[]: The voyage broken into legs. Empty when we cannot yet split it.
        - `seq` integer: Position of the leg in the rotation, starting at 1.
        - `from_unlocode` string: UN/LOCODE the leg departs.
        - `to_unlocode` string: UN/LOCODE the leg arrives at.
        - `from_name` string: Name of the departure port.
        - `to_name` string: Name of the arrival port.
        - `vessel_name` string: Name of the carrying vessel, or null when the carrier named none.
        - `voyage` string: Carrier voyage number, when published. Null otherwise.
        - `service` string: Carrier service or loop name.
        - `etd` string: Estimated time of departure (ISO 8601).
        - `eta` string: Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one.
    - `eta_intel` object: Probability envelope and reliability context. Null on thin lanes.
      - `basis` string: What the reliability figures were computed from, which tells you how much to lean on them.
      - `carrier_scoped` boolean: True when the statistics are for THIS carrier on this lane, false when they are lane-level across all carriers and therefore coarser.
      - `confidence_pct` integer: On-time percentage for the lane, which is the same number the ring shows.
      - `on_time_pct` integer: Share of sailings that arrived on time.
      - `median_delay_hours` number, nullable: Typical delay on the lane, hours. Null on a lane too thin to score.
      - `p90_delay_hours` integer: Delay that 90 percent of arrivals stay inside, hours. Null on a thin lane.
      - `observations` integer: Number of observed sailings behind the figure.
      - `window_days` integer: How far back those observations reach, days.
      - `band_low` string: Best case: the published ETA, arriving on time. Null when there is no ETA to anchor to.
      - `band_high` string: The date 90 percent of arrivals land by. Null when there is no ETA to anchor to.
      - `expected` string: The typical outcome: the ETA plus the median delay. Null when there is no ETA to anchor to.
      - `transit_p50_hours` number, nullable: Median transit time on the lane, hours. Null on a thin lane.
      - `transit_p90_hours` number, nullable: Transit time 90 percent of sailings stay inside, hours. Null on a thin lane.
    - `eta_at_risk` string, nullable: Congestion warning. Null unless the next port is congested or the vessel has waited at anchor.
    - `observability` object: Which of the four lenses we can offer on this shipment, and how many are active.
      - `lenses` object: actuals (carrier milestones), position (the vessel), plan (a schedule) and probability (a confidence figure).
        - `actuals` boolean: True when we hold carrier milestones.
        - `position` boolean: True when we hold a vessel.
        - `plan` boolean: On LoadingMCP, the computed load plan. Inside a tracking observability lens, true when we hold a schedule for the shipment.
        - `probability` boolean: True when the ETA can carry a confidence figure.
      - `active_count` integer: How many of the four lenses are present.
      - `agreement` string: Whether the sources tell the same story: aligned, diverging, partial, or insufficient when there are too few to compare.
      - `eta_sources` object[]: The ETA each cross-checkable source implies, so a disagreement can be seen rather than averaged away.
        - `lens` string: Which source this ETA came from: carrier, published or ais.
        - `eta` string: Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one.
      - `max_spread_hours` integer: Hours between the furthest-apart ETA sources. Null when fewer than two sources have an ETA.
    - `ai_insight` string, nullable: A written read of the shipment state. Null when none has been generated for this box.
    - `ai_insight_pending` boolean: True while one is being generated, so a client can poll instead of showing an empty space.
    - `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
    - `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
  - `refresh` ForceRefresh, required: What a force update achieved. Present only on POST /v1/containers/{id}/refresh.
    - `status` 'fresh' | 'timeout' | 'no_answer', required
    - `refreshed` boolean, required: True when the line answered in this request.
    - `from_cache` boolean, required: True when the detail is the answer we already held, not one from this request.
    - `reason` 'line_timeout' | 'line_no_answer' | 'refresh_failed' | 'null', nullable, required: Null when fresh. Otherwise why the detail is the stored answer.
    - `requested_at` string, date-time, required
    - `updated_at` string, date-time, nullable, required: When the line last answered about this shipment: this request when fresh, else the answer shown.
    - `refreshing_in_background` boolean, required: True while the ask is still running after the response (the timeout case).

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key is read-only. A force update needs a read_write key.
- `404`: No such shipment on this account.
- `409`: The shipment is archived. Restore it before refreshing it.
- `429`: Refreshed less than 5 minutes ago with this key. Retry after `Retry-After` seconds.

---

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