Sign in

v1

latestOpenAPI 3.0.0Cabify Api support2026-07-264588127.9 KB
Journeys

Get Journey State

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

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.

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",
  "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
  }
}