--- title: "Read tracking results" method: GET path: "/trackings/{request_id}" tags: ["Tracking"] --- # Read tracking results `GET /trackings/{request_id}` ## Request - Base URL: `https://parcelsapp.com/api-docs/mock/v4` - URL: `https://parcelsapp.com/api-docs/mock/v4/trackings/{request_id}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Reads the current state of one asynchronous tracking request. Poll this `request_id` until `done` is `true`, or use webhooks and call this endpoint only when you need to reconcile state. A request ID is not a permanent shipment subscription. Its record is eligible for deletion about 30 minutes after its last update; use `expires_at` as the expected retention boundary. HTTP 404 after that boundary is expected, and a later carrier check requires a new POST with the same tracking number. ## Path parameters - `request_id` string, required ## Response `200` Current tracking state. - TrackingResponse: One asynchronous lookup result. `request_id` can be polled until completion and remains readable only until approximately `expires_at`; create a new request for later monitoring. - `request_id` string, required: Identifier for this asynchronous lookup result, not a shipment identifier or persistent monitoring subscription. - `status` 'processing' | 'completed', required - `done` boolean, required - `expires_at` string, date-time, required: Expected retention boundary for this `request_id`, about 30 minutes after the request's last update. It is not a delivery deadline. GET may return 404 after this time; re-POST the tracking number for a later carrier check. - `results` TrackingResult[], required - `tracking_number` string, required - `state` 'processing' | 'completed', required - `from_cache` boolean, required: True when Parcels returned fresh cached data immediately instead of starting a new carrier request. - `shipment` Shipment - `trackingId` string - `error` string: Terminal shipment-level tracking error. `ADDITIONAL_FIELDS_REQUIRED` means a carrier such as SEUR needs more recipient identification to complete the lookup; this does not confirm that the tracking number exists. Inspect `input_requirements` to see required fields and alternatives, then retry with valid recipient details. `TIMEDOUT` means Parcels stopped waiting for a stale in-progress request and returned a final result instead of leaving the request processing forever. - `accepted_fields` string[]: For `ADDITIONAL_FIELDS_REQUIRED`, API v4 shipment item fields accepted for a retry. Consult `input_requirements` for which fields are required and which are alternatives. - `input_requirements` TrackingInputRequirements: Published input rule for a carrier. Absent when a complete rule has not been verified; absence does not promise that no recipient fields are needed. Required fields must be supplied together with at least one any_of field when both lists are present. - `required` TrackingInputFieldName[]: Fields to provide for every lookup. - `any_of` TrackingInputFieldName[]: Provide at least one of these fields in addition to required fields. - `conditional` TrackingInputFieldName[]: The carrier may require these fields for some shipments. Check the carrier-specific instructions for fields that must be supplied together. - `status` string - `origin` string - `destination` string - `originCode` string - `destinationCode` string - `transportMode` 'parcel' | 'postal' | 'express' | 'road_freight' | 'air_cargo' | 'ocean_container': Concrete transport mode. Forecast fallback never crosses this boundary. - `fromAirport` string: Origin IATA airport code when explicitly provided for an air-cargo shipment. - `toAirport` string: Destination IATA airport code when explicitly provided for an air-cargo shipment. - `fromPort` string: Origin UN/LOCODE when explicitly provided for an ocean shipment. - `toPort` string: Destination UN/LOCODE when explicitly provided for an ocean shipment. - `pieces` number: Shipment piece count when supplied by the carrier. - `weight` number: Shipment weight when supplied by the carrier. - `weight_unit` string: Unit for `weight`. - `volume` number: Shipment volume when supplied by the carrier. - `volume_unit` string: Unit for `volume`. - `flight_legs` FlightLeg[]: Carrier-supplied air-cargo routing legs. Schedule fields are kept separate from booking/milestone event timestamps and omitted when the carrier does not supply them. - `flight_number` string - `origin` string: Flight-leg origin IATA code. - `destination` string: Flight-leg destination IATA code. - `status` string: Carrier-reported status of this leg. - `scheduled_departure_date` string, date: Scheduled departure date when the carrier supplies a date but no reliable time. - `scheduled_departure` string, date-time: Scheduled departure with the carrier station's offset. - `scheduled_arrival` string, date-time: Scheduled arrival with the destination station's offset. - `actual_departure` string, date-time: Actual departure confirmed by the carrier. - `actual_arrival` string, date-time: Actual arrival confirmed by the carrier. - `pieces` number - `weight` number - `weight_unit` string - `volume` number - `volume_unit` string - `states` TrackingEvent[]: Carrier tracking events. Interactive prompts asking for recipient fields are omitted from API responses and webhooks; when no real events are available this array can be empty. - `state` string - `location` string - `date` string, date-time: Carrier event time with its airport-local UTC offset when the carrier provides only local wall time. - `event_code` string: Carrier milestone code when supplied by the source. - `station` string: IATA station or airport code associated with the event. - `timezone` string: IANA time zone used to interpret the carrier-local event time. - `pieces` number: Pieces covered by this event, useful for partial movements. - `weight` number: Weight covered by this event when supplied by the carrier. - `weight_unit` string - `volume` number: Volume covered by this event when supplied by the carrier. - `volume_unit` string - `flight_number` string: Flight number associated with the event. - `flight_origin` string: IATA origin of the associated flight leg. - `flight_destination` string: IATA destination of the associated flight leg. - `scheduled_departure_date` string, date: Carrier-supplied scheduled flight date when no reliable scheduled departure time is available. - `scheduled_departure` string, date-time: Carrier-supplied scheduled departure, distinct from this event's `date`. - `scheduled_arrival` string, date-time: Carrier-supplied scheduled arrival for the flight leg. - `actual_departure` string, date-time: Confirmed actual departure for the associated flight leg when available. - `actual_arrival` string, date-time: Confirmed actual arrival for the associated flight leg when available. - `uld_number` string: Unit load device number associated with the event when supplied by the carrier. - `carrier` integer - `services` Carrier[] - `slug` string - `name` string - `detectedCarrier` Carrier - `slug` string - `name` string - `detected` integer[] - `attributes` ShipmentAttribute[] - `l` string - `val` string - `code` string - `externalTracking` ExternalTracking[] - `slug` string - `url` string - `trackingId` string - `method` string - `delivery_estimate` DeliveryEstimateResult - `client_reference` string - `carrier_slug` string, required - `transport_mode` 'parcel' | 'postal' | 'express' | 'road_freight' | 'air_cargo' | 'ocean_container', required: Concrete transport mode. Forecast fallback never crosses this boundary. - `completion_scope` 'carrier_acceptance_to_delivery' | 'airport_to_airport' | 'airport_to_availability' | 'port_to_port' | 'port_to_availability' | 'port_to_gate_out', required: Defines what event counts as completion, and therefore which historical durations are compared. It is not a transport phase or route precision setting. Most callers should omit it and use the mode default. In v1 the start is the earliest confirmed physical carrier event, such as acceptance, pickup, RCS, or origin-terminal gate-in. The `airport_*` and `port_*` names describe the route family and completion boundary; they do not guarantee that the first timestamp is a flight departure or vessel departure. | Value | Measured journey | | --- | --- | | `carrier_acceptance_to_delivery` | Physical carrier acceptance or pickup to delivered/POD. Default for `parcel`, `postal`, `express`, and `road_freight`. | | `airport_to_airport` | First confirmed physical air-cargo event (often pickup or RCS) to arrival received at the destination airport (usually RCF). Default for `air_cargo`. | | `airport_to_availability` | First confirmed physical air-cargo event to ready-for-collection/available at the destination airport. | | `port_to_port` | First confirmed physical ocean event, such as origin-terminal gate-in, to arrival/discharge at the destination port. Default for `ocean_container`. | | `port_to_availability` | First confirmed physical ocean event to available/released for pickup at the destination port. | | `port_to_gate_out` | First confirmed physical ocean event to gate-out or terminal handoff at destination; this is not delivery to a final street address. | Fallback never crosses a completion-scope boundary. If the selected scope lacks enough observations, the API returns `INSUFFICIENT_DATA` rather than using a different endpoint meaning. - `route_scope_used` string: Diagnostic name of the selected statistics bucket, including whether it is carrier specific or a mode fallback. Most integrations can ignore it. - `route` DeliveryEstimateRoute: Route-selection diagnostics. Most integrations can ignore this object. - `origin_dimension` 'city' | 'admin1' | 'country' | 'airport' | 'port', nullable - `origin_key` string, nullable - `destination_dimension` 'city' | 'admin1' | 'country' | 'airport' | 'port', nullable - `destination_key` string, nullable - `carrier_specific` boolean - `estimate` DeliveryEstimateValues - `mean_days` number, required: Arithmetic mean for analytics. Use median_days as the normal point estimate. - `median_days` number, required: Primary point estimate. - `typical_days` DeliveryEstimateRange, required: Typical P10-P90 range in calendar days. - `min` number - `max` number - `remaining_status` 'not_requested' | 'estimated' | 'insufficient_censored_data' | 'insufficient_tail_data', required: Whether remaining_days was not requested, safely estimated, or withheld. insufficient_censored_data means the right-censored risk set or identifiable tail is too small; insufficient_tail_data is the fail-closed completed-tail fallback used before a survival generation exists. - `remaining_days` DeliveryEstimateRemaining, nullable: Estimated days still remaining. The censored model requires at least 100 subjects, 30 completed events, cohort age of 120 days (300 for ocean), at least five journeys and 10% of subjects in the current risk set, and identifiable P10, P50, and P90. Otherwise remaining_status explains why the API withheld it. - `mean` number, nullable: Null for Kaplan-Meier output; use median, min, and max. - `median` number - `min` number - `max` number - `estimated_delivery_at` DeliveryEstimateWindow, nullable: Estimated UTC delivery window. Present only when the request supplied a start timestamp or usable elapsed duration. - `from` string, date-time - `to` string, date-time - `confidence` DeliveryEstimateConfidence: Quality of statistical support, not the probability of delivery on one promised date. - `level` 'low' | 'medium' | 'high', required: Simple evidence-quality label for normal integrations. - `score` number, required: Diagnostic evidence-quality score, not an on-time-delivery probability. - `sample_count` integer, required - `effective_sample_count` number, required - `remaining_effective_sample_count` number: For Kaplan-Meier, the right-censored risk-set size at elapsed time; for the completed-tail fallback, time-decayed completed-tail support. Present only for a progress request. - `minimum_remaining_effective_sample_count` number: Safety floor applied by the active remaining-time method. Kaplan-Meier requires at least five journeys and 10% of subjects in the risk set, in addition to the per-mode subject floor and identifiable P10-P90 tail. - `survival_subject_count` integer - `survival_completed_count` integer - `survival_censored_count` integer - `survival_risk_set` integer - `survival_minimum_subject_count` integer - `survival_minimum_completed_count` integer - `survival_cohort_age_days` number - `survival_minimum_maturation_days` integer - `lookback_days` integer, required - `last_observation_at` string, date-time, nullable - `freshness_days` number - `fallback_level` integer, required - `model` object: Model diagnostics for reproducibility. Most integrations can ignore this object. - `version` string - `unit` 'calendar_days' - `histogram_bucket_hours` integer - `remaining_method` 'kaplan_meier_right_censored_v1' | 'completed_tail_guard_v1': Kaplan-Meier uses active right-censored journeys and delayed entry. The completed-tail guard remains a fail-closed fallback when no survival generation is published. - `error` DeliveryEstimateInsufficientData - `code` 'INSUFFICIENT_DATA', required - `message` string, required - `available_sample_count` integer, required - `minimum_sample_count` integer, required - `rejected` RejectedShipment[]: Input items rejected during per-shipment validation. Other valid items in the same batch continue normally. - `index` integer, required: Zero-based index in the submitted shipments array. - `tracking_number` string: Trimmed tracking number from the submitted item, when it was a non-empty string. - `code` 'INVALID_TRACKING_NUMBER' | 'DESTINATION_COUNTRY_REQUIRED' | 'INVALID_ADDITIONAL_FIELDS', required - `message` string, required - `webhook` WebhookRegistration: Returned only in the create response when `webhook_url` is provided. The registration belongs to this request and ends when it completes; it does not monitor the shipment afterward. Store `secret`; it is not returned again. - `url` string - `secret` string - `signature_header` string ## Other responses - `400`: Missing or invalid request_id. - `401`: Missing or invalid API key. - `404`: The request does not exist, has expired, or belongs to another account. - `429`: Too many requests from this client. - `500`: Unexpected server error. ## Changes - **2026-11-06** `dd6315a8bc4e`: 11 warning, 27 info - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `400` - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `401` - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `404` - added the new `INVALID_ADDITIONAL_FIELDS` enum value to the `error/rejected/items/code` response property for the response status `429` - …34 more - **2026-07-19** `f8d02f819394`: 1 info - endpoint added [Operation history](https://skmtc.dev/parcelsapp/apis/parcels-api-v4/changes/trackings/:request_id/get.md) --- [API](https://skmtc.dev/parcelsapp/apis/parcels-api-v4.md) - [All operations](https://skmtc.dev/parcelsapp/apis/parcels-api-v4/llms.txt) - [OpenAPI document](https://skmtc.dev/parcelsapp/apis/parcels-api-v4/revisions/dd6315a8bc4e?raw)