---
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`

## Request

- Base URL: `https://logistics.api.cabify-sandbox.com`
- URL: `https://logistics.api.cabify-sandbox.com/v1/parcels/{parcel_id}/timeline`
- Auth: HTTP bearer

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' | 'scheduled' | 'deleted', 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.
- `429`: Too many requests. This API is rate limited per account and per endpoint. A 429 is an expected condition rather than a failed request: back off and retry it. The limits are not the same for every endpoint and can change, so handle the status instead of hard-coding a rate. See the Limits and reliability guide.

---

[API](https://skmtc.dev/cabify/apis/cabify-logistics-api.md) - [All operations](https://skmtc.dev/cabify/apis/cabify-logistics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cabify/apis/cabify-logistics-api/revisions/dff49457aac9?raw)