Read a resource's tracking state and the movements its carrier reported.

Poll this until is_terminal is true, by the resource_id the dispatch response gave you.

tracking_status and current_state answer different questions and an empty events list needs both to be read: TRACKING with no events means Genesis is watching and the carrier has reported nothing yet, while NOT_TRACKED means Genesis never watched this resource -- because its carrier has not confirmed the booking, or because the id is not one of yours.

current_state is Genesis's reading of what the carrier's own codes mean, derived when you read rather than frozen when the movement arrived, so a correction to a carrier's vocabulary reaches history that was already recorded. A movement whose code means nothing for the shipment's state is published with shipment_state: null and does not move current_state: the carrier reported something real, it simply does not move the freight.

SecurityAPIKeyHeader
Request
path Parameters
resource_id
required
string (Resource Id)
query Parameters
limit
integer (Limit) [ 1 .. 250 ]
Default: 100

How many movements to return. A timeline is normally tens of them.

cursor
string (Cursor) <= 512 characters

The next_cursor of the previous page, passed back unchanged. Opaque: its contents are not a contract and may gain fields.

A walk is live rather than a snapshot. It resumes by position, and a movement's position is the time its carrier gave it, so a movement reported late -- one whose own timestamp falls behind a page you have already read -- is not in the pages that remain. Read without a cursor to see the whole timeline again; current_state is derived over all of it either way and never depends on where a walk has got to.

header Parameters
X-Shipwell-Version
string (X-Shipwell-Version)

Pins this request to the API as it behaved on the given ISO date, e.g. 2026-08-25. Omitted or unparseable means the oldest behaviour, so a client that never sends it keeps the behaviour it was written against.

Responses
200

Successful Response

Response Schema: application/json
required
object (TrackingResult)

Where one resource's freight is, and every movement its carrier reported.

Two questions, answered by two fields that must not be read as one. tracking_status says whether Genesis is watching this resource at all; current_state says where the freight is. An empty events list therefore has two readings and the pair tells them apart: TRACKING with no events means Genesis is watching and the carrier has said nothing yet, while NOT_TRACKED means Genesis never watched this resource.

Polling is the completion signal, the same as every other public surface here: stop on is_terminal and on nothing else.

400

Validation Error

404

Not returned for a resource_id: an unknown id, or one belonging to another company, answers 200 with tracking_status NOT_TRACKED.

500

An unknown internal server issue occured while processing a request. A report is created and logged.

get/tracking/timelines/{resource_id}
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
Copyright © Shipwell 2025. All right reserved.