The “Get Driver Timeline Info” API retrieves the timeline events and status changes for a specific driver within an organization over a given time range. This includes derived job events, driver status at the time of each event, and the geographic location where each event occurred, enabling fleet operators to reconstruct and audit driver activity across a shift.

¶ Use case

The Get Driver Timeline Info API enables fleet operators to query the complete sequence of events for a single driver during a specified time window. This is useful for building activity audit tools, post-shift review dashboards, or any system that needs to understand how a driver’s status evolved over time — from coming online, receiving job offers, completing pickups and dropoffs, to session pauses and job cancellations. The API returns a chronological list of events with associated driver status and coordinates, giving a full picture of driver activity within the requested time range.

¶ Support for Hierarchical Data

Not Supported. The API returns timeline data for the single driver specified in the request, within the given organization. It does not support fetching data across multiple drivers or child organizations in one call.

¶ Supported Supplier Types

Fleets

¶ Scope

Primary - supplier.driver.activity.read

¶ Resource

/v1/vehicle-suppliers/driver/timeline-info

¶ HTTP Method

POST

¶ Authorization

Client Credentials

¶ Example Request

curl -i -X POST "https://api.uber.com/v1/vehicle-suppliers/driver/timeline-info" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "request": {
    "org_id": "2e5bb117-dc86-4188-85a5-3337d91f1e05",
    "driver_uuid": "48202b44-6866-4b98-9e27-6332348e31c1",
    "start_time": 1773187200000,
    "end_time": 1774483200000
  }
}'

¶ Example Response

{
  "driverUuid": "48202b44-6866-4b98-9e27-6332348e31c1",
  "eventsAndStatus": [
    {
      "event": "JOB_OFFERED",
      "location": {
        "latitude": 38.899349,
        "longitude": -122.414592
      },
      "status": "STATUS_ONLINE",
      "eventTime": "1773187200002"
    },
    {
      "event": "JOB_ASSIGNED",
      "location": {
        "latitude": 38.899500,
        "longitude": -122.414700
      },
      "status": "STATUS_ENROUTE",
      "eventTime": "1773187200003"
    }
  ]
}

¶ Request Body Fields

Name	Type	Required	Description
request.org_id	string (UUID)	Y	Organization UUID for which the driver belongs.
request.driver_uuid	string (UUID)	Y	Driver UUID to fetch timeline info for.
request.start_time	int64	Y	Start timestamp in milliseconds (epoch). Timeline events on and after this timestamp will be included. Must be non-zero and less than or equal to end_time.
request.end_time	int64	Y	End timestamp in milliseconds (epoch). Timeline events on and before this timestamp will be included. Must be non-zero and greater than or equal to start_time. The difference between end_time and start_time must not exceed 24 hours (86,400,000 milliseconds).

¶ Response Body Fields

Name	Type	Nullable	Description
driverUuid	string (UUID)	N	The driver UUID from the request.
eventsAndStatus	Array of EventAndStatus	N	Chronological list of timeline events and statuses for the driver within the requested time range.

EventAndStatus

Name	Type	Nullable	Description
event	string (enum)	N	The derived event name. See Event for valid values.
location	Location object	N	Geographic coordinate where the event occurred.
status	string (enum)	N	The driver’s status at the time of the event. See DriverStatus for valid values.
eventTime	string	N	Timestamp of the event in Unix epoch milliseconds (UTC).

Location

Name	Type	Description
latitude	double	Latitude of the location where the event occurred.
longitude	double	Longitude of the location where the event occurred.

Event

Event	Definition
JOB_OFFERED	A job offer is presented to the driver.
JOB_ASSIGNED	The driver accepts the job; trip is assigned.
JOB_REJECTED	The driver actively declines the job offer.
PICKUP_ARRIVED	Driver marks arrived at pickup location.
PICKUP_COMPLETED	Driver marks the pickup as completed.
JOB_COMPLETED	The driver marks the trip as completed.
JOB_CANCELLED	The job offer expired before the driver responded.
SESSION_PAUSED	Driver session paused.
SESSION_UNPAUSED	Driver session resumed.
"" (empty string)	No state change events exist for the driver in the requested time range.

DriverStatus

Status	Definition
STATUS_ONLINE	Driver is online and available.
STATUS_ENROUTE	Driver is en route to the pickup location.
STATUS_ARRIVED	Driver has arrived at the pickup location.
STATUS_ONTRIP	Driver is on a trip en route to the dropoff location.
STATUS_DROPPED_OFF	Driver has completed the dropoff.
STATUS_UNASSIGNABLE	Driver is temporarily unavailable (session paused).
STATUS_OFFLINE	Driver is offline. Returned when no state change events exist for the requested time range.

Event to Status Mapping

The following table shows the mapping between each timeline event and the driver status returned alongside it.

Event	Status
JOB_OFFERED	STATUS_ONLINE
JOB_ASSIGNED	STATUS_ENROUTE
JOB_REJECTED	STATUS_ONLINE
PICKUP_ARRIVED	STATUS_ARRIVED
PICKUP_COMPLETED	STATUS_ONTRIP
JOB_COMPLETED	STATUS_DROPPED_OFF
JOB_CANCELLED	STATUS_ONLINE
SESSION_PAUSED	STATUS_UNASSIGNABLE
SESSION_UNPAUSED	STATUS_ONLINE
"" (empty string)	STATUS_OFFLINE

¶ Rate Limit

• Rate limit for this endpoint is 50 requests per 10 seconds per Developer Application.

¶ Endpoint Specific Errors

Http Status Code	Code	Message
400	missing_argument	Request is nil.
400	invalid_argument	Invalid Organization Id.
400	invalid_argument	Invalid Driver UUID.
400	invalid_argument	start_time and end_time are required.
400	invalid_argument	start_time must be less than or equal to end_time.
400	invalid_argument	The time range between start_time and end_time must not exceed 24 hours.
401	unauthorized	User does not have permission to perform operation in the org.
500	internal_server_error	Unable to fetch timeline info for the driver.

¶ Notes

• Both org_id and driver_uuid must be passed in their decrypted (raw UUID) form in the request payload.
• You can obtain driver UUIDs (driverId) from the Get Drivers Information API, which returns both raw and encrypted driver UUIDs.
• Exactly one driver_uuid must be provided per request; the API does not support fetching timeline data for multiple drivers in a single call.
• start_time and end_time are both inclusive: events occurring exactly at either boundary timestamp will be included in the response.
• The time range between start_time and end_time must not exceed 24 hours (86,400,000 milliseconds). Requests exceeding this range will be rejected with an INVALID_ARGUMENT error.
• The webhook ([Webhook] Realtime Driver Status Change) and this API can go out of sync, because of the nature of async processing of events.
• eventTime is returned as a string representing Unix epoch milliseconds (UTC).
• Events are derived from Chronicle internal state types and mapped to the external event format by the vs-analytics service.

¶ FAQ

• Does the API support sandbox environments?
  • No, the API does not currently support sandbox environments.
• Can I fetch timeline data for multiple drivers in one request?
  • No. The API requires a single driver_uuid per request. To retrieve timeline data for multiple drivers, make separate requests for each driver.