Journeys

Get Journey State

Changed on Nov 3, 2026

Returns the real-time operational state of an active journey: assigned driver, vehicle, and the route waypoints collected so far.

Use this endpoint for live tracking while a journey is in progress. It provides the data needed to show the driver's position on a map and display vehicle/driver details to the rider.

Typical use cases:

Show the assigned driver's name, phone number, and avatar.
Display the vehicle plate, model, and color so the rider can identify it.
Plot the driver's route on a map using the waypoints array.

Availability:

Returns data once a driver is assigned (hired state onward).
Returns empty waypoints for journeys in terminated state (route data is archived).
Returns 404 if the journey does not exist or does not belong to the authenticated client.

⚠️ Stop polling once you receive an end state

End states are terminal, the journey will never transition to another state. Once you receive an end state (via this endpoint or a webhook), stop polling. Continued polling returns 200 with state: terminated indefinitely but carries no new information.

For reliable state delivery without polling, configure Journey State Updates webhooks.

📘 Looking for booking details or pricing?

To retrieve stops, cost breakdown, or lifecycle status, use the Get Journey Details endpoint instead.

To receive state changes in real time without polling, configure Webhooks.

get/api/v4/journey/{id}/state

Request

Base URL
https://cabify-sandbox.com
URL
https://cabify-sandbox.com/api/v4/journey/{id}/state
Auth
HTTP bearer

Path parameters

idstring required

UUID of the journey

Query parameters

requester_idstring required

ID of the user who requested the journey

Response

Success

is_driver_on_another_journeyboolean

Whether the assigned driver is currently completing another trip before heading to the pickup.

journey_idstring

UUID of the journey.

locnumber[] nullable

Current location of the vehicle as [latitude, longitude]. It is an empty array when the state carries no usable position, and null for journeys whose live state has already been archived (returned together with name: "terminated").

Current state of the journey. The end states (drop off, rider cancel, driver cancel, no show, not found) are terminal: stop polling once you receive one. unknown is returned when we receive a state we do not recognise yet; ignore those events and let us know if they break a flow.

Example response

{
  "driver": {
    "avatar_url": "https://secure.gravatar.com/avatar/675ee8c314586d36a7b33c6c773565e9?r=pg&s=80&=blank",
    "id": "e8417e8cd14c11ec869eb2e3f32e3b38",
    "name": "John",
    "phone_number": "34611111111"
  },
  "driver_stop_before_pickup": {
    "loc": [
      40.4201,
      -3.7056
    ]
  },
  "is_driver_on_another_journey": true,
  "journey_id": "f0397896-19aa-11ed-b6fe-7aaea8067492",
  "loc": [
    40.4169335,
    -3.7061872
  ],
  "name": "hired",
  "preassigned_driver": {
    "avatar_url": "https://secure.gravatar.com/avatar/1a79a4d60de6718e8e5b326e338ae533?r=pg&s=80&=blank",
    "id": "a1b2c3d4e5f611ec869eb2e3f32e3b38",
    "name": "Diana"
  },
  "vehicle": {
    "color": "red",
    "name": "Seat ibiza",
    "plate": "QXJ4758"
  },
  "waypoints": {
    "rows": [
      {
        "loc": [
          40.4169335,
          -3.7061872
        ],
        "state_name": "hired"
      }
    ],
    "total": 48
  }
}

Changes

Nov 3, 202622a12845e173 Revision changes
- breaking
  the response property became nullable for the status
- breaking
  the response property became nullable for the status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  the response's property type changed from object to no type for status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status

Operation history