---
title: "Get the state history of a parcel."
method: GET
path: "/v1/parcels/{parcel_id}/timeline"
tags: ["status"]
---

# Get the state history of a parcel.

`GET /v1/parcels/{parcel_id}/timeline`

Returns the ordered list of state-change events for the specified parcel. Only parcels updated within the last 30 days can be queried.

## Path parameters

- `parcel_id` string, uuid, required

## Response `200`

Timeline retrieved successfully.

- ParcelTimeline
  - `id` string, uuid, required — System-generated UUID for this parcel.
  - `external_id` string — Your own identifier for this parcel, as provided when the parcel was created.
  - `timeline` TimelineEvent[], required — Chronological list of state-change events for this parcel.
    - `state` 'ready' | 'qualifiedforpickup' | 'pickingup' | 'intransit' | 'delivering' | 'delivered' | 'returning' | 'returned' | 'incident' | 'requestercancel' | 'internalcancel' | 'pickupfailed' | 'onroutetopickup' | 'readytopickup' | 'onroutetofinalhub' | 'receivedonfinalhub' | 'readytodispatch' | 'onroutetodelivery' | 'undelivered' | 'onroutetoreturn' | 'returnrejected', required — The lifecycle state the parcel transitioned into. See [parcel states](https://developers.cabify.com/reference/logistics-introduction#parcel) for a full description of each value.
    - `state_updated_at` string, date-time, required — Timestamp when the parcel transitioned into this state, formatted according to RFC 3339, section 5.6.

## Other responses

- `401` — Unauthorized. Missing or invalid authentication token.
- `403` — This parcel does not belong to your account.
- `404` — No parcel found with the given ID.

---

[API](https://skmtc.dev/cabify/apis/ride-hailing-api.md) · [All operations](https://skmtc.dev/cabify/apis/ride-hailing-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cabify/ride-hailing-api/revisions/8da1cb1270df/schema)