PAparcelsapp
Tracking

Read tracking results

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.

get/trackings/{request_id}

Request

Path parameters

request_idstring required
Example:66f4f2c0e16b4c13bb7e0001

The request_id returned by POST /trackings.

Response

Current tracking state.

request_idstring required

Identifier for this asynchronous lookup result, not a shipment identifier or persistent monitoring subscription.

status'processing' | 'completed' required
doneboolean required
expires_atstring 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.

Example response

{
  "request_id": "66f4f2c0e16b4c13bb7e0001",
  "status": "completed",
  "done": true,
  "expires_at": "2026-06-25T19:13:20.000Z",
  "results": [
    {
      "tracking_number": "9400111206213785678901",
      "state": "completed",
      "from_cache": true,
      "shipment": {
        "trackingId": "9400111206213785678901",
        "error": "TIMEDOUT",
        "accepted_fields": [
          "postal_code",
          "email",
          "phone"
        ],
        "status": "delivered",
        "origin": "United States",
        "destination": "United States",
        "originCode": "US",
        "destinationCode": "US",
        "fromAirport": "BRU",
        "toAirport": "DAR",
        "fromPort": "HKHKG",
        "toPort": "JPTYO",
        "pieces": 13,
        "weight": 385,
        "weight_unit": "kg",
        "volume": 1.67,
        "volume_unit": "m3",
        "flight_legs": [
          {
            "flight_number": "QR-8416",
            "origin": "DOH",
            "destination": "ALA",
            "status": "Booked",
            "scheduled_departure_date": "2026-09-02",
            "scheduled_departure": "2026-09-02T13:37:00+03:00",
            "scheduled_arrival": "2026-09-02T20:11:00+05:00",
            "actual_departure": "2026-09-02T13:37:00+03:00",
            "actual_arrival": "2026-09-02T20:25:00+05:00",
            "pieces": 34,
            "weight": 2608,
            "weight_unit": "kg",
            "volume": 32.07,
            "volume_unit": "m3"
          }
        ],
        "states": [
          {
            "state": "Delivered, In/At Mailbox",
            "location": "Austin, TX, United States",
            "date": "2026-06-25T18:42:00.000Z",
            "event_code": "DEP",
            "station": "DEL",
            "timezone": "Asia/Kolkata",
            "pieces": 13,
            "weight": 385,
            "weight_unit": "kg",
            "volume": 0.71,
            "volume_unit": "m3",
            "flight_number": "AI-2243",
            "flight_origin": "DOH",
            "flight_destination": "ALA",
            "scheduled_departure_date": "2026-09-02",
            "scheduled_departure": "2026-09-02T13:37:00+03:00",
            "scheduled_arrival": "2026-09-02T20:11:00+05:00",
            "actual_departure": "2026-09-02T13:37:00+03:00",
            "actual_arrival": "2026-09-02T20:25:00+05:00",
            "uld_number": "BT005AI"
          }
        ],
        "services": [
          {
            "slug": "usps",
            "name": "USPS"
          }
        ],
        "detectedCarrier": {
          "slug": "usps",
          "name": "USPS"
        },
        "detected": [
          0
        ],
        "attributes": [
          {
            "l": "origin",
            "val": "United States",
            "code": "US"
          }
        ],
        "externalTracking": [
          {
            "slug": "usps",
            "url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213785678901",
            "trackingId": "9400111206213785678901",
            "method": "GET"
          }
        ]
      },
      "delivery_estimate": {
        "model": {
          "version": "delivery-forecast-v1.2",
          "histogram_bucket_hours": 6
        },
        "error": {
          "minimum_sample_count": 8
        }
      }
    }
  ],
  "rejected": [
    {
      "index": 1,
      "tracking_number": "1",
      "code": "INVALID_TRACKING_NUMBER",
      "message": "tracking_number is not valid for tracking."
    }
  ],
  "webhook": {
    "url": "https://example.com/parcels/webhook",
    "secret": "whsec_abc123",
    "signature_header": "Parcels-Signature"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.