--- title: "Get the route, tracking events and ETA revisions of a shipment" method: GET path: "/shipments/{shipment_id}/timeline" tags: ["Shipments"] --- # Get the route, tracking events and ETA revisions of a shipment `GET /shipments/{shipment_id}/timeline` ## Request - Base URL: `https://trackberry.com/api/v1` - URL: `https://trackberry.com/api/v1/shipments/{shipment_id}/timeline` - Auth: HTTP bearer Use this to answer "where is it and what happened" and "how has the ETA moved". Returns the route legs in order, every tracking event (both events that happened and estimated ones, oldest first) and every recorded revision of the estimated arrival, oldest first. Not paged. ## Path parameters - `shipment_id` string, required ## Headers - `Trackberry-Version` string ## Response `200` The timeline of the shipment. - Timeline: The route, tracking events and ETA history of one shipment. - `object` 'timeline', required: Always `timeline`. - `shipment_id` string, required: The shipment this timeline belongs to. - `legs` ShipmentLeg[], required: The legs of the route in travel order. - `object` 'shipment_leg', required: Always `shipment_leg`. - `id` string, required: The leg id. - `position` integer, required: The zero-based order of the leg in the route. Not the same as `leg_index` on tracking events. - `transport_type` 'ocean' | 'air' | 'road' | 'null', nullable, required: How the cargo travels on this leg. - `carrier` string, nullable, required: The carrier of this leg, as written in the transport document. - `transport_reference` string, nullable, required: The bill of lading, air waybill or consignment number of this leg. - `origin` Place, required: An origin or a destination. - `location` string, nullable, required: The city or port, normalized (for example `Rotterdam`), without the country. - `country` string, nullable, required: The country's English name (for example `Netherlands`). - `timezone` string, nullable, required: The UTC offset of the place as `+HH:MM` or `-HH:MM` (for example `+02:00`), learned from carrier data. Not an IANA time zone name. - `destination` Place, required: An origin or a destination. - `location` string, nullable, required: The city or port, normalized (for example `Rotterdam`), without the country. - `country` string, nullable, required: The country's English name (for example `Netherlands`). - `timezone` string, nullable, required: The UTC offset of the place as `+HH:MM` or `-HH:MM` (for example `+02:00`), learned from carrier data. Not an IANA time zone name. - `etd` string, date-time, nullable, required: Departure time of this leg, from the transport document. - `eta` string, date-time, nullable, required: Arrival time of this leg, from the transport document. - `events` TrackingEvent[], required: Tracking events, oldest first. Events without a time are placed by the usual order of milestones. - `object` 'tracking_event', required: Always `tracking_event`. - `id` string, required: The event id. - `milestone` 'booked' | 'received_from_shipper' | 'empty_pickup' | 'stuffed' | 'gate_in' | 'manifested' | 'loaded' | 'departed' | 'transshipment_arrival' | 'transshipment_discharge' | 'transferred' | 'transshipment_load' | 'transshipment_departure' | 'arrived' | 'discharged' | 'held' | 'hold_released' | 'customs_cleared' | 'notified' | 'available_for_pickup' | 'gate_out' | 'cfs_released' | 'delivered' | 'stripped' | 'empty_return' | 'eta_revised' | 'exception' | 'untracked', required: What happened, from Trackberry's own milestone vocabulary (never a carrier's raw code). Cargo milestones in usual order: `booked`, `received_from_shipper` (air), `empty_pickup`, `stuffed`, `gate_in`, `manifested` (air), `loaded`, `departed`, `transshipment_arrival`, `transshipment_discharge`, `transferred` (air), `transshipment_load`, `transshipment_departure`, `arrived`, `discharged`, `held` and `hold_released` (a hold on the box at the destination terminal, reported only by a terminal feed and timed when first seen), `customs_cleared`, `notified` (air), `available_for_pickup`, `gate_out`, `cfs_released` (LCL, when the forwarder releases the cargo at its freight station; known to the day only, so `occurred_at` is 00:00Z of that day), `delivered`, `stripped`, `empty_return`. Lifecycle milestones: `eta_revised`, `exception`, `untracked`. `discharged` (off the vessel) and `gate_out` (left the terminal) start and stop the demurrage clock. - `actual` boolean, required: True when the event has happened; false when it is an estimate of a future or unconfirmed milestone. - `occurred_at` string, date-time, nullable, required: When the event happened (or is expected to), in UTC. Null when the source gave no time. - `occurred_at_local` string, date-time, nullable, required: The same instant written with the UTC offset of the place it happened (for example `2026-09-10T09:20:00-05:00`), when the source reported the offset; otherwise the UTC time. Null when `occurred_at` is null. - `container_number` string, nullable, required: The container the event is about. Null for events about the whole shipment. - `leg_index` integer, nullable, required: The one-based number of the vessel or flight leg of the journey the event belongs to, as counted from the carrier's event sequence (1 is the first leg, 2 comes after a transshipment). Not the `position` of a shipment leg. Null when the source does not say. - `location` object, required: Where the event happened. - `name` string, nullable, required: The place name, such as a port or an airport. - `code` string, nullable, required: The location code as reported, a UN/LOCODE for ports (for example `NLRTM`) where available. - `country_code` string, nullable, required: The ISO 3166-1 alpha-2 country code. - `vessel` object, required: The vessel involved, for ocean events. - `name` string, nullable, required: The vessel name. - `imo` string, nullable, required: The vessel's IMO number. - `voyage` string, nullable, required: The voyage number. - `flight_number` string, nullable, required: The flight, for air events. - `position` object, required: Coordinates of the event, when the source gave them. - `latitude` number, nullable, required: Latitude in decimal degrees. - `longitude` number, nullable, required: Longitude in decimal degrees. - `eta_revisions` EtaRevision[], required: Every recorded change of the estimated arrival, oldest first. - `object` 'eta_revision', required: Always `eta_revision`. - `id` string, required: The revision id. - `observed_at` string, date-time, required: When Trackberry saw the new estimate. For `backfilled` revisions this is only the time of the last refresh, not when the carrier changed its mind. - `previous_eta` string, date-time, nullable, required: The estimate before this revision. Null for the first estimate ever learned. - `new_eta` string, date-time, required: The estimate after this revision. - `slip_seconds` number, nullable, required: How much later the arrival got, in seconds (`new_eta` minus `previous_eta`). Negative when the carrier moved the arrival earlier. Null for the first estimate, because there is nothing to compare with. - `first_estimate` boolean, required: True for the opening quote, when there was no previous estimate. - `backfilled` boolean, required: True when the revision was reconstructed from older data, so `observed_at` is not the moment the change happened. Leave these out when measuring how fast schedules slip. ## Other responses - `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400. - `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header. - `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one. - `404`: No such object in this organization (`resource_missing`). This is also the answer for an id of another organization, an id with the wrong prefix, or a malformed id, so the API never confirms that an object exists elsewhere. - `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced. --- [API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)