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 '{
  "org_id": "2e5bb117-dc86-4188-85a5-3337d91f1e05",
  "driver_uuid": "48202b44-6866-4b98-9e27-6332348e31c1",
  "start_time": 1773187200000,
  "end_time": 1774483200000
}'

¶ Example Response

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

¶ Request Body Fields

Name	Type	Required	Description
org_id	string (UUID)	Y	Organization UUID for which the driver belongs.
driver_uuid	string (UUID)	Y	Driver UUID to fetch timeline info for.
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.
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.

¶ Response Body Fields

Name	Type	Nullable	Description
driver_uuid	string (UUID)	N	The driver UUID from the request.
events_and_status	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.
event_time	int64	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.
NA	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.

¶ Rate Limit

• Rate limit for this endpoint is 10,000 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.
403	PERMISSION_DENIED	User does not have permission to perform operation in the org.
500	INTERNAL	Unable to fetch timeline info for the driver.

¶ Notes

• 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.
• event_time values are expressed in 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.