--- title: "[legacy] Get Driver efficiency data grouped by drivers." method: GET path: "/driver-efficiency/drivers" tags: ["Legacy APIs"] --- # \[legacy\] Get Driver efficiency data grouped by drivers. `GET /driver-efficiency/drivers` ## Request - Base URL: `https://api.samsara.com` - URL: `https://api.samsara.com/driver-efficiency/drivers` - Auth: HTTP bearer **⚠️ LEGACY/DEPRECATED API: This API returns data from the legacy Driver Efficiency (Eco-Driving) product and is unavailable to new customers. Use the Driver Efficiency (Eco-Driving) dataset in the beta [Custom Reports API](https://developers.samsara.com/reference/createreportrun) for equivalent data.** This endpoint will return driver efficiency data that has been collected for your organization and grouped by drivers based on the time parameters passed in. Results are paginated. **Note:** The data from this endpoint comes from the Driver Efficiency (Eco-Driving) Report. The existing [/fleet/drivers/efficiency](https://developers.samsara.com/reference/getdriverefficiency) endpoint has now been moved to Legacy. Rate limit: 10 requests/sec (learn more about rate limits here). To use this endpoint, select **Read Driver Efficiency** under the Fuel & Energy category when creating or editing an API token. Learn More. **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team. ## Query parameters - `startTime` string, required - `endTime` string, required - `driverIds` string[] - `dataFormats` string[] - `tagIds` string - `parentTagIds` string - `after` string ## Response `200` OK response. - DriverEfficiencyGetDriverEfficiencyByDriversResponseBody - `data` SingleDriverEfficiencyByDriverDataObjectResponseBody[], required: List of driver efficiency data associated with drivers. - `difficultyScore` DriverEfficiencyDifficultyScoreDataObjectResponseBody: Difficulty score won't be available if there is no data to compute it against. - `overallScore` string: Represents the overall difficulty score. It has scores from 1 to 5. - `topographyScore` string: Represents the topography difficulty score. It has scores from 1 to 5. - `vehicleWeightScore` string: Represents the average vehicle weight score. It has scores from 1 to 5. - `driverId` string, required: ID of the driver. - `percentageData` DriverEfficiencyPercentageDataObjectResponseBody: Driver Efficiency percentage data. This object is returned when the “percentage” format is specified in “dataFormats”. - `anticipationPercentage` number, double: Percentage of time a driver is in quickly breaking events vs total breaking events. - `coastingPercentage` number, double: Percentage of time a driver is in coasting. - `cruiseControlPercentage` number, double: Percentage of time a vehicle is in cruise control. - `greenBandPercentage` number, double: Percentage of time a driver is driving within the green band. - `highGradeRoadDrivingPercentage` number, double: Percentage of time a driver is driving on high-grade road. - `highTorquePercentage` number, double: Percentage of time a driver is driving in high torque. - `idlingPercentage` number, double, required: Percentage of time a driver is idling. - `overSpeedPercentage` number, double: Percentage of time a driver is in over-speeding. - `wearFreeBrakePercentage` number, double: Percentage of time a driver is in wear-free breaking. - `rawData` DriverEfficiencyRawDataObjectResponseBody: Driver Efficiency raw data. This object is returned when the “raw” format is specified in “dataFormats”. - `anticipationBrakeEventCount` integer: Total number of quick braking events (less than one second after accelerating). - `averageVehicleWeightKg` integer: Average vehicle weight in kilograms. - `coastingDurationMs` integer: Time spent without engaging the accelerator or brake in milliseconds. - `cruiseControlDurationMs` integer: Time spent in cruise control in milliseconds. - `driveTimeDurationMs` integer, required: Total driving time in milliseconds. - `engineOnDurationMs` integer, required: Total engine-on time in milliseconds. - `greenBandDurationMs` integer: Time spent driving within the configurable green band in milliseconds. - `highGradeRoadDrivingDurationMs` integer: Time spent driving on high-grade roads in milliseconds. - `highTorqueDurationMs` integer: Time the vehicle engine torque is greater than 90% in milliseconds. - `idlingDurationMs` integer, required: Time spent idling in milliseconds. - `overSpeedDurationMs` integer: Time spent over-speeding in milliseconds. - `totalBrakeDurationMs` integer, required: Total breaking time in milliseconds. - `totalBrakeEventCount` integer: Total number of brake events. - `wearFreeBrakeDurationMs` integer: Time spent ware-free breaking in milliseconds. - `scoreData` DriverEfficiencyDataObjectResponseBody: Driver Efficiency score data. This object is returned by default or when the “score” format is specified in “dataFormats”. - `anticipationScore` string: Represents the anticipation score for the driver. The score will be in either number or letter format depending on the organisation config. - `coastingScore` string: Represents the coasting score for the driver. The score will be in either number or letter format depending on the organisation config. - `cruiseControlScore` string: Represents the cruise control score for the driver. The score will be in either number or letter format depending on the organisation config. - `greenBandScore` string: Represents the green band score for the driver. The score will be in either number or letter format depending on the organisation config. - `highTorqueScore` string: Represents the high torque score for the driver. The score will be in either number or letter format depending on the organisation config. - `idlingScore` string: Represents the idling score for the driver.The score will be in either number or letter format depending on the organisation config. - `overSpeedScore` string: Represents the over speed score for the driver. The score will be in either number or letter format depending on the organisation config. - `overallScore` string, required: Represents the overall score for the driver. The score will be in either number (0-100) as a string or letter format (A-G) depending on the organisation config. - `wearFreeBrakeScore` string: Represents the ware-free breaking score for the driver. The score will be in either number or letter format depending on the organisation config. - `pagination` GoaPaginationResponseResponseBody, required: Pagination parameters. - `endCursor` string, required: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view. - `hasNextPage` boolean, required: True if there are more pages of results immediately available after this endCursor. ## Other responses - `401`: Unauthorized response. - `404`: Not Found response. - `405`: Method Not Allowed response. - `413`: Content Too Large response. - `429`: Too Many Requests response. - `500`: Internal Server Error response. - `501`: Not Implemented response. - `502`: Bad Gateway response. - `503`: Service Unavailable response. - `504`: Gateway Timeout response. - `default`: Bad Request response. --- [API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)