GETAPI key

Container detail

GETapi.trackingmcp.com/v1/containers/{id}

The full record: status, route, vessel, milestone timeline and the basis for the ETA. This is the widest payload in the API and it carries more keys than the example below, including the per-field provenance envelope. The fields shown are the stable core.

Path parameters

idstringrequired

The container UUID returned by create, list or lookup. Not the container number.

Response fields

Derived from the example response.

okboolean

Whether the request succeeded.

dataobject

The payload. Everything an endpoint returns sits under this key.

data.idstring

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.

data.identifierstring

The container number, bill of lading or booking this record tracks.

data.identifier_typestring

What the identifier is. The keyed surface uses container_id, bill_of_lading or booking; the public tracker returns booking_number for the third.

data.container_numberstring

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.

data.bl_numbernull

The bill of lading, or null when the record was not tracked by one.

data.booking_numbernull

The booking reference, or null when the record was not tracked by one.

data.carrier_codestring

Carrier SCAC.

data.carrier_namestring

Carrier name.

data.statusstring

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.

data.etastring

Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one.

data.eta_is_estimatedboolean

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.

data.eta_confidence_pctnumber

How often this lane arrives on time, as a percentage. Null on a lane too thin to score.

data.origin_unlocodestring

Origin port UN/LOCODE, or null when the carrier named no origin we could resolve.

data.destination_unlocodestring

Destination port UN/LOCODE, or null when unresolved.

data.destination_namestring

Destination port name, falling back to its UN/LOCODE.

data.container_sizestring

Equipment size, for example 40HC. Null when the carrier did not state it.

data.child_containersnull

The boxes a bill of lading or booking resolves to, each with its own timeline. Null on a plain container lookup.

data.history_daysnumber

How far back the timeline reaches on your plan, in days.

data.is_demoboolean

True on a sample reference. Sample boxes return typical data and have no live carrier feed.

data.last_polled_atstring

When we last asked the carrier (ISO 8601).

data.last_ais_fix_atstring

When the vessel was last actually observed by AIS, or null when we hold no fix.

data.last_updated_atstring

The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment.

data.last_updated_sourcestring

Which of the two produced last_updated_at: carrier_poll or ais_vessel_position. Null when neither has happened yet.

data.field_provenance_summaryobject

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".

data.field_provenance_summary.resolvednumber

Declared fields we hold a value for.

data.field_provenance_summary.contract_requirednumber

Declared fields that stay empty until you supply your own free-time terms.

data.field_provenance_summary.not_publishednumber

Declared fields this carrier does not publish.

data.field_provenance_summary.not_applicablenumber

Declared fields that do not apply to this shipment.

data.field_provenance_summary.awaiting_carriernumber

Declared fields we expect but have not received yet.

data.field_provenance_summary.unblocked_by_contract_termsboolean

True when supplying free-time terms would fill at least one empty field.

data.eventsobject[]

Milestone timeline, oldest to newest.

data.events[].event_typestring

DCSA event category: SHIPMENT, TRANSPORT or EQUIPMENT.

data.events[].event_classifier_codestring

DCSA classifier: ACT, EST or PLN.

data.events[].event_codestring

Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA. Null when the carrier sent none.

data.events[].event_date_timestring

When the event happened or is forecast to (ISO 8601).

data.events[].transport_callobject

The location, vessel and voyage of the port call. Null when the carrier gave no call.

data.events[].transport_call.locationobject

UN/LOCODE for the event, or null when the carrier gave no place.

data.events[].transport_call.location.UNLocationCodestring

UN/LOCODE.

data.vessel_positionobject

Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet.

data.vessel_position.imostring

IMO number of the vessel.

data.vessel_position.namestring

Human-readable name.

data.vessel_position.latnumber

Latitude.

data.vessel_position.lngnumber

Longitude.

data.vessel_position.speed_knotsnumber

Speed over ground, in knots.

data.vessel_position.position_freshnessstring

live, recent, stale, outdated, or unknown when we hold no usable fix.

data.transshipmentnull

The hub the box is dwelling at and its onward vessel. Null unless it is dwelling.

data.eta_intelnull

Probability envelope and reliability context. Null on thin lanes.

data.eta_at_risknull

Congestion warning. Null unless the next port is congested or the vessel has waited at anchor.

Errors

A failure carries { "ok": false, "error": { "code", "message", "severity" } }. Branch on the code, and log the message.

UNAUTHORIZED401

The key is missing, malformed or revoked.

NOT_FOUND404

No container with that UUID on your account. Note the id is the UUID, not the container number.

curl 'https://api.trackingmcp.com/v1/containers/8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY"

const res = await fetch("https://api.trackingmcp.com/v1/containers/8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef", {
  headers: {
    "Authorization": "Bearer tmcp_YOUR_API_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.trackingmcp.com/v1/containers/8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
    headers={"Authorization": "Bearer tmcp_YOUR_API_KEY"},
)
data = res.json()

Response

{
  "ok": true,
  "data": {
    "id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
    "identifier": "MEDU1234562",
    "identifier_type": "container_id",
    "container_number": "MEDU1234562",
    "bl_number": null,
    "booking_number": null,
    "carrier_code": "MSCU",
    "carrier_name": "MSC",
    "status": "in_transit",
    "eta": "2026-07-03T06:00:00Z",
    "eta_is_estimated": true,
    "eta_confidence_pct": 78,
    "origin_unlocode": "CNNGB",
    "destination_unlocode": "NLRTM",
    "destination_name": "Rotterdam",
    "container_size": "40HC",
    "child_containers": null,
    "history_days": 90,
    "is_demo": false,
    "last_polled_at": "2026-08-07T08:40:00Z",
    "last_ais_fix_at": "2026-08-07T08:12:00Z",
    "last_updated_at": "2026-08-07T08:40:00Z",
    "last_updated_source": "carrier_poll",
    "field_provenance_summary": {
      "resolved": 5,
      "contract_required": 2,
      "not_published": 1,
      "not_applicable": 0,
      "awaiting_carrier": 0,
      "unblocked_by_contract_terms": true
    },
    "events": [
      {
        "event_type": "TRANSPORT",
        "event_classifier_code": "ACT",
        "event_code": "DEPA",
        "event_date_time": "2026-06-18T22:10:00Z",
        "transport_call": { "location": { "UNLocationCode": "CNNGB" } }
      }
    ],
    "vessel_position": {
      "imo": "9754105",
      "name": "MSC TERESA",
      "lat": 36.12,
      "lng": 14.55,
      "speed_knots": 17.4,
      "position_freshness": "live"
    },
    "transshipment": null,
    "eta_intel": null,
    "eta_at_risk": null
  }
}