---
title: "Get Journey State"
method: GET
path: "/api/v4/journey/{id}/state"
tags: ["Journeys"]
---

# Get Journey State

`GET /api/v4/journey/{id}/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](https://developers.cabify.com/docs/journey-updates-webhook).

> 📘 Looking for booking details or pricing?
>
> To retrieve stops, cost breakdown, or lifecycle status, use the
> [Get Journey Details](#operation/getJourney) endpoint instead.
>
> To receive state changes in real time without polling, configure
> [Webhooks](https://developers.cabify.com/docs/journey-updates-webhook).

## Path parameters

- `id` string, required

## Query parameters

- `requester_id` string, required

## Response `200`

Success

- JourneyState — Real-time operational state of an active journey: the assigned driver, their vehicle, and the route waypoints recorded so far.
  - `driver` Driver — Driver's information.
    - `avatar_url` string — Driver's picture.
    - `id` string — Id of the driver
    - `name` string — Driver's name.
    - `phone_number` string — Driver's phone number.
  - `driver_stop_before_pickup` DriverStopBeforePickup, nullable — Best-effort location where the driver is heading before coming to the pickup. May be null even when is_driver_on_another_journey is true.
    - `loc` number[] — Latitude and longitude of the driver's current destination.
  - `is_driver_on_another_journey` boolean — Whether the assigned driver is currently completing another trip before heading to the pickup.
  - `journey_id` string — UUID of the journey.
  - `preassigned_driver` PreassignedDriver, nullable — Driver preassigned to the journey (for example on a reservation) before the journey is actually assigned. It does not include the phone number, and it may change or disappear before the journey starts. `driver` always takes precedence: once a driver is assigned, that `driver` is authoritative and this field is only informative about who had been preassigned.
    - `avatar_url` string — Preassigned driver's picture.
    - `id` string — Id of the preassigned driver
    - `name` string — Preassigned driver's first name.
  - `vehicle` Vehicle — Journey's vehicle information.
    - `color` string — Vehicle color.
    - `name` string — Vehicle model.
    - `plate` string — Vehicle plate number.
  - `waypoints` Waypoint — Information about the different points through which the driver passed during the journey.
    - `rows` Row[] — List of each point and state through which the driver passed during the journey.
      - `loc` number[] — The actual coordinates of the address. Required floats per location latitude and longitude.
      - `state_name` string — Status of the journey at the time the driver passed through that point.
    - `total` integer, nullable — Total number of rows

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found
- `500` — Internal server error

---

[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)