GETAPI key

List tracked containers

GETapi.trackingmcp.com/v1/containers

Every container on your account, most recently updated first.

Query parameters

statusstring

Filter to one status, for example in_transit, discharged, customs_hold, delivered.

limitinteger

Page size. Default 50, capped at 500.

cursorstring

Pass the next_cursor from the previous page.

tagsstring

Comma-separated tags. A row must carry all of them.

archivedboolean

Set true to list archived boxes instead of the active fleet. Default false.

Response fields

Derived from the example response.

okboolean

Whether the request succeeded.

dataobject

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

data.itemsobject[]

The list of results.

data.items[].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.items[].identifierstring

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

data.items[].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.items[].carrier_codestring

Carrier SCAC.

data.items[].carrier_namestring

Carrier name.

data.items[].tagsany[]

Your own labels on this box. Filter the list endpoint with them.

data.items[].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.items[].etastring

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

data.items[].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.items[].origin_unlocodestring

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

data.items[].destination_unlocodestring

Destination port UN/LOCODE, or null when unresolved.

data.items[].destination_namestring

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

data.items[].container_sizestring

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

data.items[].demurrage_at_riskboolean

True when the free-time clock on this box is a concern.

data.items[].demurrage_last_free_daynull

The last day before demurrage accrues, or null when no terms are on file.

data.items[].last_polled_atstring

When we last asked the carrier (ISO 8601).

data.items[].added_atstring

When you started tracking this box (ISO 8601).

data.items[].archived_atnull

When tracking stopped, or null while the box is still active.

data.items[].is_demoboolean

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

data.items[].route_portsstring[]

The ports on the route, in order.

data.items[].delay_barsnull[]

Days late at each of the five voyage stages. Positive is late, negative is early, null means we cannot tell.

data.items[].vessel_positionobject

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

data.items[].vessel_position.imostring

IMO number of the vessel.

data.items[].vessel_position.namestring

Human-readable name.

data.items[].vessel_position.latnumber

Latitude.

data.items[].vessel_position.lngnumber

Longitude.

data.items[].vessel_position.speed_knotsnumber

Speed over ground, in knots.

data.items[].vessel_position.heading_degnumber

Heading in degrees.

data.items[].vessel_position.nav_statusstring

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.

data.items[].vessel_position.position_updated_atstring

When we last wrote the position row.

data.items[].vessel_position.position_fix_atstring

When the hull was actually observed. This, not position_updated_at, is the age that matters.

data.items[].vessel_position.position_age_hoursnumber

How old the fix is, in hours.

data.items[].vessel_position.position_freshnessstring

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

data.has_moreboolean

True when another page is waiting behind next_cursor.

data.next_cursornull

Cursor for the next page, or null when there are no more.

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.

INTERNAL_ERROR500

The query failed or timed out. Retry with a smaller limit.

curl 'https://api.trackingmcp.com/v1/containers' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY"

const res = await fetch("https://api.trackingmcp.com/v1/containers", {
  headers: {
    "Authorization": "Bearer tmcp_YOUR_API_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.trackingmcp.com/v1/containers",
    headers={"Authorization": "Bearer tmcp_YOUR_API_KEY"},
)
data = res.json()

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
        "identifier": "MEDU1234562",
        "identifier_type": "container_id",
        "carrier_code": "MSCU",
        "carrier_name": "MSC",
        "tags": [],
        "status": "in_transit",
        "eta": "2026-07-03T06:00:00Z",
        "eta_is_estimated": true,
        "origin_unlocode": "CNNGB",
        "destination_unlocode": "NLRTM",
        "destination_name": "Rotterdam",
        "container_size": "40HC",
        "demurrage_at_risk": false,
        "demurrage_last_free_day": null,
        "last_polled_at": "2026-08-07T08:40:00Z",
        "added_at": "2026-07-29T11:02:00Z",
        "archived_at": null,
        "is_demo": false,
        "route_ports": ["CNNGB", "NLRTM"],
        "delay_bars": [null, 0, null, 2, null],
        "vessel_position": {
          "imo": "9754105",
          "name": "MSC TERESA",
          "lat": 36.12,
          "lng": 14.55,
          "speed_knots": 17.4,
          "heading_deg": 291,
          "nav_status": "Under way using engine",
          "position_updated_at": "2026-08-07T08:15:00Z",
          "position_fix_at": "2026-08-07T08:12:00Z",
          "position_age_hours": 0.6,
          "position_freshness": "live"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}