The “Get Driver Timeline Info” API retrieves the timeline events and status changes for a specific earner within an organization over a given time range. This includes derived job events, earner status at the time of each event, and the geographic location where each event occurred, enabling fleet operators to reconstruct and audit earner 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 earner 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 earner’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 earner status and coordinates, giving a full picture of earner activity within the requested time range.

¶ Support for Hierarchical Data

Not Supported. The API returns timeline data for the single earner specified in the request, within the given organization. It does not support fetching data across multiple earners 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 earner belongs.
request.driver_uuid	string (UUID)	Y	Earner 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 earner UUID from the request.
eventsAndStatus	Array of EventAndStatus	N	Chronological list of timeline events and statuses for the earner 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 earner’s status at the time of the event. See EarnerStatus 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 earner.
JOB_ASSIGNED	The earner accepts the job; trip is assigned.
JOB_REJECTED	The earner actively declines the job offer.
PICKUP_ARRIVED	Earner marks arrived at pickup location.
PICKUP_COMPLETED	Earner marks the pickup as completed.
JOB_COMPLETED	The earner marks the trip as completed.
JOB_CANCELLED	The job offer expired before the earner responded.
SESSION_PAUSED	Earner session paused.
SESSION_UNPAUSED	Earner session resumed.
"" (empty string)	No state change events exist for the Earner in the requested time range.

EarnerStatus

Status	Definition
STATUS_ONLINE	Earner is online and available.
STATUS_ENROUTE	Earner is en route to the pickup location.
STATUS_ARRIVED	Earner has arrived at the pickup location.
STATUS_ONTRIP	Earner is on a trip en route to the dropoff location.
STATUS_DROPPED_OFF	Earner has completed the dropoff.
STATUS_UNASSIGNABLE	Earner is temporarily unavailable (session paused).
STATUS_OFFLINE	Earner 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 earner 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 earner 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 earners 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 earners in one request?
  • No. The API requires a single driver_uuid per request. To retrieve timeline data for multiple earners, make separate requests for each earner.