Safety Scores
Safety Scores are the figures of the Safety Scores page of the Manifold portal: how safely each of your vehicles and drivers drove over the latest completed week, month or quarter, how that compares with the period before and with your other vehicles, how many incidents it had and how far it drove. They also give you the data to draw the portal's Vehicle Safety Score Distribution chart yourself.
Scores run from 0 to 100, and a high score is safe. Each score is the mean of the vehicle's daily scores over the period. Scores are computed nightly, and every response says in asOf the latest day it covers (UTC). You can compare each vehicle with the period before, find vehicles whose score is low or falling, see the leading risk factors behind a score, and compare your fleet with your own vehicles and with Manifold-wide reference values. Only the latest completed week, month or quarter can be requested, not an earlier one.
| Endpoint | What it returns |
|---|---|
GET /reports/safety-scores/summary | The fleet's average score against the previous period and the Manifold benchmark, the daily trend, the leading risk factors, and the five lowest and highest scoring vehicles |
GET /reports/safety-scores/vehicles | The vehicle table, one page at a time: score, previous score, distance, incidents, quartile and rank in connection of each vehicle, plus the score distribution |
GET /reports/safety-scores/export | The same vehicles, all in one answer (at most 20,000) |
GET /reports/safety-scores/drivers | The driver table, one page at a time: score, previous score, distance, quartile and rank in connection of each driver, plus the score distribution |
GET /reports/safety-scores/drivers/export | The same drivers, all in one answer (at most 20,000) |
All five need your x-api-key and the Analytics feature on your account; without it they answer 403. They do not use the Connection-Id header: they cover all your live connections, or one of them when you send connectionId.
Query parameters
| Parameter | Type | Routes | Description |
|---|---|---|---|
range | string | all | Required. week (the latest completed week, Monday to Sunday), month (the latest completed calendar month) or quarter (the latest three completed months). The period ends on asOf, that day included (UTC). The period before it has the same length and ends the day before this one starts |
connectionId | UUID | all | Only the vehicles of this connection. One of your own connections, otherwise 400 |
vehicleGroupIds | array | summary, vehicles, export | Only the vehicles of these vehicle groups. Repeat the parameter for each group; a vehicle that belongs to any of the groups is included |
vehicleIds | array | summary, vehicles, export | Only these vehicles. Repeat the parameter for each vehicle |
driverGroupIds | array | drivers, drivers/export | Only the drivers of these driver groups. Repeat the parameter for each group; a driver that belongs to any of the groups is included |
driverIds | array | drivers, drivers/export | Only these drivers. Repeat the parameter for each driver |
factor | string | vehicles, export, drivers, drivers/export | Only vehicles or drivers that have this risk factor (for example tailgating) among their three leading factors. It does not return every vehicle that showed that behavior or condition, only those where it was a leading factor |
scoreFrom, scoreTo | number | vehicles, export, drivers, drivers/export | Only scores from scoreFrom (included) up to scoreTo (not included; 100 includes 100). Between 0 and 100, and scoreFrom not above scoreTo |
search | string | vehicles, export, drivers, drivers/export | Only vehicles whose name or VIN, or drivers whose name or employee number, contains the text. Ignored when shorter than two characters |
sort | string | vehicles, export, drivers, drivers/export | score (default), change (the change from the previous score), distance or name |
desc | boolean | vehicles, export, drivers, drivers/export | Sort from high to low. The default, false, sorts from low to high (with sort=score, the lowest scores first) |
page | integer | vehicles, drivers | The page, starting at 1 (default 1) |
pageSize | integer | vehicles, drivers | Vehicles or drivers per page, 1 to 100 (default 10) |
Example request
curl --request GET \
--url "https://api.analytics.autos/reports/safety-scores/vehicles?range=month&connectionId=6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b&sort=name&pageSize=5" \
--header 'x-api-key: YOUR-API-KEY'Example response
GET /reports/safety-scores/vehicles. The real response has 100 entries in fineHistogram; only the first five are shown here.
{
"status": 200,
"message": null,
"data": {
"asOf": "2026-10-31",
"window": {
"from": "2026-10-01",
"to": "2026-10-31",
"previousFrom": "2026-08-31",
"previousTo": "2026-09-30"
},
"total": 48,
"rows": [
{
"vehicleId": "0b5f3c1e-7a42-4d8e-9c10-2f6a8b3d5e71",
"name": "Unit 02",
"vin": "1FTFW1E50NFA00002",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": ["Night shift"],
"provider": "Geotab",
"score": 91.2,
"previousScore": 89.7,
"distanceM": 3912400.0,
"scoredDays": 30,
"incidents": 0,
"quartile": 4,
"rankInConnection": 2,
"vehiclesInConnection": 48,
"factors": [
{ "key": "speeding", "kind": "behavior", "days": 6 },
{ "key": "timeOnRoad", "kind": "exposure", "days": 21 }
]
},
{
"vehicleId": "3d9a7e52-1c64-4b0f-8a37-5e2c9d1f6b84",
"name": "Unit 07",
"vin": "1FTFW1E50NFA00007",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": ["North", "Night shift"],
"provider": "Geotab",
"score": 43.2,
"previousScore": 47.9,
"distanceM": 4217300.0,
"scoredDays": 30,
"incidents": 11,
"quartile": 1,
"rankInConnection": 48,
"vehiclesInConnection": 48,
"factors": [
{ "key": "tailgating", "kind": "behavior", "days": 22 },
{ "key": "hardBraking", "kind": "behavior", "days": 17 },
{ "key": "nightDriving", "kind": "exposure", "days": 12 }
]
},
{
"vehicleId": "a84e1d06-9b73-4f25-b6c8-7d0e3a2f9c15",
"name": "Unit 11",
"vin": "1FTFW1E50NFA00011",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": ["North"],
"provider": "Geotab",
"score": 71.4,
"previousScore": 70.1,
"distanceM": 3388900.0,
"scoredDays": 29,
"incidents": 3,
"quartile": 2,
"rankInConnection": 27,
"vehiclesInConnection": 48,
"factors": [
{ "key": "laneDeparture", "kind": "behavior", "days": 8 },
{ "key": "weather", "kind": "environment", "days": 5 }
]
},
{
"vehicleId": "c2f6b390-4e18-4a7d-8d5b-1a9e7c3f0d62",
"name": "Unit 14",
"vin": "1FTFW1E50NFA00014",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": [],
"provider": "Geotab",
"score": 71.4,
"previousScore": 73.0,
"distanceM": 3051200.0,
"scoredDays": 30,
"incidents": 4,
"quartile": 2,
"rankInConnection": 27,
"vehiclesInConnection": 48,
"factors": [
{ "key": "distractedDriving", "kind": "behavior", "days": 9 },
{ "key": "hardAcceleration", "kind": "behavior", "days": 7 },
{ "key": "congestion", "kind": "environment", "days": 4 }
]
},
{
"vehicleId": "e17d4a85-0b2c-4f93-a6e1-8c5d2b7f3a09",
"name": "Unit 21",
"vin": "1FTFW1E50NFA00021",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": ["South"],
"provider": "Geotab",
"score": 80.6,
"previousScore": null,
"distanceM": 1204800.0,
"scoredDays": 12,
"incidents": 1,
"quartile": 3,
"rankInConnection": 12,
"vehiclesInConnection": 48,
"factors": [
{ "key": "seatbelt", "kind": "behavior", "days": 3 }
]
}
],
"histogram": [
{ "from": 0, "to": 5, "count": 0 },
{ "from": 5, "to": 10, "count": 0 },
{ "from": 10, "to": 15, "count": 0 },
{ "from": 15, "to": 20, "count": 0 },
{ "from": 20, "to": 25, "count": 0 },
{ "from": 25, "to": 30, "count": 0 },
{ "from": 30, "to": 35, "count": 0 },
{ "from": 35, "to": 40, "count": 0 },
{ "from": 40, "to": 45, "count": 1 },
{ "from": 45, "to": 50, "count": 1 },
{ "from": 50, "to": 55, "count": 2 },
{ "from": 55, "to": 60, "count": 4 },
{ "from": 60, "to": 65, "count": 4 },
{ "from": 65, "to": 70, "count": 5 },
{ "from": 70, "to": 75, "count": 6 },
{ "from": 75, "to": 80, "count": 8 },
{ "from": 80, "to": 85, "count": 9 },
{ "from": 85, "to": 90, "count": 5 },
{ "from": 90, "to": 95, "count": 2 },
{ "from": 95, "to": 100, "count": 1 }
],
"fineHistogram": [
{ "from": 0, "to": 1, "count": 0 },
{ "from": 1, "to": 2, "count": 0 },
{ "from": 2, "to": 3, "count": 0 },
{ "from": 3, "to": 4, "count": 0 },
{ "from": 4, "to": 5, "count": 0 }
],
"bandCounts": [8, 15, 17, 8],
"fleetAverage": 72.6,
"benchmark": {
"average": 68.4
},
"bands": {
"cutPoints": [60, 75, 85],
"source": "manifold"
},
"notes": []
},
"next": null
}Fields of a vehicle
| Field | Description |
|---|---|
vehicleId | The vehicle's Manifold id |
name | The vehicle's name, or its VIN when it has no name |
vin | The vehicle identification number |
connectionId, connectionName | The connection the vehicle's rank is taken in, and its name |
groupNames | The vehicle groups the vehicle belongs to |
provider | The telematics provider of the connection |
score | The mean daily score over the period, 0 to 100. High is safe |
previousScore | The same score over the period before, of the same length. null when the vehicle had no score then. The change is score minus previousScore: a positive change is an improvement |
distanceM | Metres driven in the period |
scoredDays | Days of the period on which the vehicle was scored |
incidents | The number of the vehicle's confirmed incidents in the period of these types: hard braking, hard acceleration, hard cornering, late braking, tailgating, near collision, lane departure, distracted driving, no seat belt, partial seat belt, red-light violation, stop-sign violation and improper yield. They are the incident types of Incident Insights in the portal. Speeding is not counted (it has its own page), and neither are accidents. The count is not the same thing as factors: a vehicle can have leading risk factors with 0 incidents. 0 when there were none; null when the counts could not be read (see notes) |
quartile | The band the score falls in, from 1 (the lowest scores, the riskiest quarter) to 4 (the highest, the safest). See Quartiles and bands |
rankInConnection | The vehicle's place among the scored vehicles of its connection: 1 is the highest score. Vehicles with the same score share a place, and the next place is skipped (two vehicles in second place are followed by fourth). See Rank in connection |
vehiclesInConnection | The number of scored vehicles rankInConnection is out of |
factors | The vehicle's leading risk factors, at most three, the leading one first. key is the factor (tailgating, hardBraking, nightDriving, weather and so on), kind is the category: behavior (how the vehicle was driven), exposure (when or where it was driven, such as night driving) or environment (conditions such as weather), and days is the number of days of the period on which it was among the vehicle's three leading factors. days is not a count of incidents |
Fields of the response
| Field | Description |
|---|---|
asOf | The latest day the scores cover (UTC). The period ends on this day |
window | from and to (the period, both days included), and previousFrom and previousTo (the period before) |
total | The vehicles that match all your filters, before paging |
rows | The requested page of vehicles |
histogram | The score distribution in twenty 5-point bins: [0,5), [5,10) and so on up to [95,100] |
fineHistogram | The same distribution in one hundred 1-point bins, [0,1) up to [99,100] |
bandCounts | The vehicles in each of the four bands, the lowest scores first |
fleetAverage | The mean score of the vehicles the distribution covers |
benchmark | average: the mean score across all Manifold clients. null, with a BENCHMARK_SUPPRESSED note, when too few clients contribute for it to be shown. A benchmark.average that is present always comes without that note |
bands | The cut points that split scores into four bands, and their source |
notes | Explains anything that is missing or incomplete. See Notes |
Each bin of histogram and fineHistogram has from, to and count.
Quartiles and bands
bands.cutPoints holds three whole-number cut points. With the cut points [60, 75, 85] of the example:
quartile | Scores | Meaning |
|---|---|---|
| 1 | below 60 | The lowest scores: the riskiest quarter |
| 2 | 60 up to, not including, 75 | |
| 3 | 75 up to, not including, 85 | |
| 4 | 85 to 100 | The highest scores: the safest quarter |
bands.source tells you where the cut points come from:
manifold: the 25th, 50th and 75th percentiles of the scores of all Manifold clients, so each band holds about a quarter of all Manifold vehicles. They do not necessarily split your own fleet into four equal groups.default: the benchmark is not available, so fixed cut points (45, 60 and 80) are used. Then the bands are not measured quartiles.
The cut points are the same for every vehicle of a period, whatever your filters. They come from that period's benchmark, so a week and a month can have different cut points, and the bands of drivers differ from those of vehicles.
Rank in connection
The rank is taken among all the scored vehicles (or drivers) of the connection, whatever filters you send: asking for ten vehicles, or for one group, never changes a vehicle's rank. The rank and vehiclesInConnection (driversInConnection) are null when your fleet has more than 20,000 scored vehicles (drivers) (a RANKS_UNAVAILABLE note says so); quartile is still given then. They are also null when the scores needed for the rank could not be read (TIMEOUT or SOURCE_ERROR on rows in notes), and for a row that has no connection. quartile is null only when bands.cutPoints is null.
A vehicle that is merged across several connections is ranked once, in the connection its score is recorded on.
Drawing the score distribution
The Vehicle Safety Score Distribution chart of the portal is a histogram of the scores with the four bands coloured:
- Call
GET /reports/safety-scores/vehicleswith therangeand the connection, vehicle group or vehicle filters you want. A smallpageSizeis enough: the distribution does not depend on the page. - Draw one bar for each entry of
fineHistogram(orhistogramfor coarser bars):fromandtoare the bar's score range andcountits height. - Colour each bar by the band of its score, using
bands.cutPoints. Every cut point is a whole number, so no 1-point bar holds two bands. - Mark
fleetAverageand, when it is there,benchmark.average. - For the number of vehicles in each band, use
bandCounts, which counts the exact scores. The 5-point bins cannot give it when a cut point falls inside a bin.
The distribution covers the vehicles of the connectionId, vehicleGroupIds and vehicleIds you send. The filters combine: a vehicle must be in the connection, in any of the groups, and in the list of ids, when you send each. The table filters (factor, scoreFrom, scoreTo and search) narrow only total and rows.
Drivers
GET /reports/safety-scores/drivers is the driver table of the portal's Safety Scores page. It takes range, connectionId, driverGroupIds, driverIds, factor, scoreFrom, scoreTo, search, sort, desc, page and pageSize, and answers like the vehicle table: a page of rows, total, the score distribution, bands and notes. The distribution covers the drivers of the connection, driver group and driver filters, and the bands and benchmark are those of drivers.
GET /reports/safety-scores/drivers/export takes the same parameters without page and pageSize and returns every matching driver, at most 20,000 (truncated is true past that).
GET /reports/safety-scores/drivers. The real response has 100 entries in fineHistogram; only the first five are shown here.
{
"status": 200,
"message": null,
"data": {
"asOf": "2026-10-31",
"window": {
"from": "2026-10-01",
"to": "2026-10-31",
"previousFrom": "2026-08-31",
"previousTo": "2026-09-30"
},
"total": 36,
"rows": [
{
"driverId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Ann Lee",
"employeeNumber": "E-1017",
"currentVehicle": {
"vehicleId": "0b5f3c1e-7a42-4d8e-9c10-2f6a8b3d5e71",
"name": "Unit 02"
},
"currentVehicleSource": "assigned",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"provider": "Geotab",
"groupNames": ["Night shift"],
"score": 93.1,
"previousScore": 91.4,
"distanceM": 3650200.0,
"scoredDays": 31,
"previousScoredDays": 30,
"quartile": 4,
"rankInConnection": 1,
"driversInConnection": 36,
"factors": [
{ "key": "timeOnRoad", "kind": "exposure", "days": 20 }
]
},
{
"driverId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"name": "Bo Chen",
"employeeNumber": "E-1042",
"currentVehicle": {
"vehicleId": "3d9a7e52-1c64-4b0f-8a37-5e2c9d1f6b84",
"name": "Unit 07"
},
"currentVehicleSource": "lastDriven",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"provider": "Geotab",
"groupNames": ["North", "Night shift"],
"score": 42.6,
"previousScore": 49.0,
"distanceM": 4012900.0,
"scoredDays": 31,
"previousScoredDays": 31,
"quartile": 1,
"rankInConnection": 36,
"driversInConnection": 36,
"factors": [
{ "key": "tailgating", "kind": "behavior", "days": 21 },
{ "key": "hardBraking", "kind": "behavior", "days": 16 },
{ "key": "nightDriving", "kind": "exposure", "days": 11 }
]
},
{
"driverId": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f",
"name": "Cy Diaz",
"employeeNumber": "E-1088",
"currentVehicle": null,
"currentVehicleSource": null,
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"provider": "Geotab",
"groupNames": ["North"],
"score": 71.4,
"previousScore": 70.2,
"distanceM": null,
"scoredDays": 29,
"previousScoredDays": 28,
"quartile": 2,
"rankInConnection": 18,
"driversInConnection": 36,
"factors": [
{ "key": "laneDeparture", "kind": "behavior", "days": 8 },
{ "key": "weather", "kind": "environment", "days": 5 }
]
},
{
"driverId": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f80",
"name": "Di Evans",
"employeeNumber": null,
"currentVehicle": {
"vehicleId": "0b5f3c1e-7a42-4d8e-9c10-2f6a8b3d5e71",
"name": "Unit 02"
},
"currentVehicleSource": "assigned",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"provider": "Geotab",
"groupNames": [],
"score": 80.6,
"previousScore": null,
"distanceM": 1204800.0,
"scoredDays": 12,
"previousScoredDays": 0,
"quartile": 3,
"rankInConnection": 9,
"driversInConnection": 36,
"factors": [
{ "key": "seatbelt", "kind": "behavior", "days": 3 }
]
}
],
"histogram": [
{ "from": 0, "to": 5, "count": 0 },
{ "from": 5, "to": 10, "count": 0 },
{ "from": 10, "to": 15, "count": 0 },
{ "from": 15, "to": 20, "count": 0 },
{ "from": 20, "to": 25, "count": 0 },
{ "from": 25, "to": 30, "count": 0 },
{ "from": 30, "to": 35, "count": 0 },
{ "from": 35, "to": 40, "count": 0 },
{ "from": 40, "to": 45, "count": 1 },
{ "from": 45, "to": 50, "count": 1 },
{ "from": 50, "to": 55, "count": 1 },
{ "from": 55, "to": 60, "count": 3 },
{ "from": 60, "to": 65, "count": 3 },
{ "from": 65, "to": 70, "count": 4 },
{ "from": 70, "to": 75, "count": 4 },
{ "from": 75, "to": 80, "count": 6 },
{ "from": 80, "to": 85, "count": 6 },
{ "from": 85, "to": 90, "count": 4 },
{ "from": 90, "to": 95, "count": 2 },
{ "from": 95, "to": 100, "count": 1 }
],
"fineHistogram": [
{ "from": 0, "to": 1, "count": 0 },
{ "from": 1, "to": 2, "count": 0 },
{ "from": 2, "to": 3, "count": 0 },
{ "from": 3, "to": 4, "count": 0 },
{ "from": 4, "to": 5, "count": 0 }
],
"bandCounts": [6, 11, 12, 7],
"fleetAverage": 71.9,
"benchmark": {
"average": 69.2
},
"bands": {
"cutPoints": [60, 75, 85],
"source": "manifold"
},
"notes": []
},
"next": null
}GET /reports/safety-scores/drivers/export:
{
"status": 200,
"message": null,
"data": {
"asOf": "2026-10-31",
"window": {
"from": "2026-10-01",
"to": "2026-10-31",
"previousFrom": "2026-08-31",
"previousTo": "2026-09-30"
},
"rows": [
{
"driverId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Ann Lee",
"employeeNumber": "E-1017",
"currentVehicle": null,
"currentVehicleSource": null,
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"provider": "Geotab",
"groupNames": ["Night shift"],
"score": 93.1,
"previousScore": 91.4,
"distanceM": 3650200.0,
"scoredDays": 31,
"previousScoredDays": 30,
"quartile": 4,
"rankInConnection": 1,
"driversInConnection": 36,
"factors": [
{ "key": "timeOnRoad", "kind": "exposure", "days": 20 }
]
},
{
"driverId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"name": "Bo Chen",
"employeeNumber": "E-1042",
"currentVehicle": {
"vehicleId": "3d9a7e52-1c64-4b0f-8a37-5e2c9d1f6b84",
"name": "Unit 07"
},
"currentVehicleSource": "lastDriven",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"provider": "Geotab",
"groupNames": ["North", "Night shift"],
"score": 42.6,
"previousScore": 49.0,
"distanceM": 4012900.0,
"scoredDays": 31,
"previousScoredDays": 31,
"quartile": 1,
"rankInConnection": 36,
"driversInConnection": 36,
"factors": [
{ "key": "tailgating", "kind": "behavior", "days": 21 },
{ "key": "hardBraking", "kind": "behavior", "days": 16 },
{ "key": "nightDriving", "kind": "exposure", "days": 11 }
]
}
],
"truncated": false,
"notes": []
},
"next": null
}| Field of a driver | Description |
|---|---|
driverId | The driver's Manifold id |
name | The driver's name, or Driver when it is blank |
employeeNumber | The driver's employee number |
currentVehicle | vehicleId and name of the vehicle the driver is assigned to now. On a page of drivers, a driver without an assignment gets the vehicle of their newest trip in the period. null when there is none, and always null for an unassigned driver in the export |
currentVehicleSource | assigned or lastDriven; null exactly when currentVehicle is |
connectionId, connectionName, provider, groupNames | The connection the driver's rank is taken in, its name and telematics provider, and the driver's groups |
score, previousScore | The mean daily score over the period and over the period before (null when the driver had no score then). 0 to 100, high is safe |
distanceM | Metres driven in the period. null when the driver's provider does not attribute trips to drivers: the distance is unknown, not zero |
scoredDays, previousScoredDays | Days of the period, and of the period before, on which the driver was scored. A change that rests on few previousScoredDays is weak |
quartile | The band the score falls in, from 1 (the lowest scores) to 4 (the highest), against the cut points of bands. Same rules as for vehicles |
rankInConnection, driversInConnection | The driver's place among the scored drivers of their connection (1 is the highest score; equal scores share a place) and the number of drivers it is out of. Never changed by your filters |
factors | The driver's leading risk factors, at most three, as for vehicles |
Drivers have no incident count in these reports.
Summary
GET /reports/safety-scores/summary takes range, connectionId, vehicleGroupIds and vehicleIds.
{
"status": 200,
"message": null,
"data": {
"asOf": "2026-11-15",
"window": {
"from": "2026-11-09",
"to": "2026-11-15",
"previousFrom": "2026-11-02",
"previousTo": "2026-11-08"
},
"fleet": {
"average": 72.9,
"previousAverage": 71.8,
"scoredVehicles": 48,
"totalVehicles": 52
},
"benchmark": {
"average": null
},
"bands": {
"cutPoints": [45, 60, 80],
"source": "default"
},
"trend": [
{ "date": "2026-11-09", "average": 72.1 },
{ "date": "2026-11-10", "average": 72.4 },
{ "date": "2026-11-11", "average": null },
{ "date": "2026-11-12", "average": 73.0 },
{ "date": "2026-11-13", "average": 73.2 },
{ "date": "2026-11-14", "average": 72.8 },
{ "date": "2026-11-15", "average": 72.9 }
],
"factors": [
{ "key": "tailgating", "kind": "behavior", "vehiclesAffected": 14, "previousVehiclesAffected": 17 },
{ "key": "hardBraking", "kind": "behavior", "vehiclesAffected": 11, "previousVehiclesAffected": 9 },
{ "key": "nightDriving", "kind": "exposure", "vehiclesAffected": 9, "previousVehiclesAffected": 9 },
{ "key": "laneDeparture", "kind": "behavior", "vehiclesAffected": 6, "previousVehiclesAffected": 7 },
{ "key": "weather", "kind": "environment", "vehiclesAffected": 4, "previousVehiclesAffected": 2 }
],
"lowest": [
{
"vehicleId": "3d9a7e52-1c64-4b0f-8a37-5e2c9d1f6b84",
"name": "Unit 07",
"vin": "1FTFW1E50NFA00007",
"score": 41.7,
"previousScore": 46.2,
"distanceM": 985400.0,
"scoredDays": 7,
"factors": [
{ "key": "tailgating", "kind": "behavior", "days": 6 },
{ "key": "hardBraking", "kind": "behavior", "days": 5 },
{ "key": "nightDriving", "kind": "exposure", "days": 3 }
],
"connectionName": "Acme Fleet",
"groupNames": ["North", "Night shift"],
"provider": "Geotab"
},
{
"vehicleId": "5a8c2e47-6d10-4b93-8f2a-9e3b7d1c4a60",
"name": "Unit 33",
"vin": "1FTFW1E50NFA00033",
"score": 47.8,
"previousScore": 52.0,
"distanceM": 674100.0,
"scoredDays": 7,
"factors": [
{ "key": "hardCornering", "kind": "behavior", "days": 5 }
],
"connectionName": "Acme Fleet",
"groupNames": ["North"],
"provider": "Geotab"
},
{
"vehicleId": "7b1d9f30-2a85-4c6e-b4d7-0f8a3e5c2b91",
"name": "Unit 40",
"vin": "1FTFW1E50NFA00040",
"score": 52.5,
"previousScore": null,
"distanceM": 188000.0,
"scoredDays": 4,
"factors": [
{ "key": "tailgating", "kind": "behavior", "days": 3 },
{ "key": "nightDriving", "kind": "exposure", "days": 2 }
],
"connectionName": "Acme Fleet",
"groupNames": [],
"provider": "Geotab"
},
{
"vehicleId": "9c3e5a71-8d24-4e0b-a1f6-3b7d9c2e5f18",
"name": "Unit 05",
"vin": "1FTFW1E50NFA00005",
"score": 55.1,
"previousScore": 54.0,
"distanceM": 720500.0,
"scoredDays": 7,
"factors": [
{ "key": "lateBraking", "kind": "behavior", "days": 4 }
],
"connectionName": "Acme Fleet",
"groupNames": ["Night shift"],
"provider": "Geotab"
},
{
"vehicleId": "b4d6f812-3e57-4a9c-8c20-5a1e7b9d3f46",
"name": "Unit 18",
"vin": "1FTFW1E50NFA00018",
"score": 58.3,
"previousScore": 60.2,
"distanceM": 655700.0,
"scoredDays": 7,
"factors": [
{ "key": "laneWeaving", "kind": "behavior", "days": 3 }
],
"connectionName": "Acme Fleet",
"groupNames": ["South"],
"provider": "Geotab"
}
],
"highest": [
{
"vehicleId": "d6f8a034-5b79-4c1e-9a42-7c3e1d5b9f20",
"name": "Unit 09",
"vin": "1FTFW1E50NFA00009",
"score": 96.4,
"previousScore": 95.8,
"distanceM": 798300.0,
"scoredDays": 7,
"factors": [
{ "key": "timeOnRoad", "kind": "exposure", "days": 7 }
],
"connectionName": "Acme Fleet",
"groupNames": ["North"],
"provider": "Geotab"
},
{
"vehicleId": "0b5f3c1e-7a42-4d8e-9c10-2f6a8b3d5e71",
"name": "Unit 02",
"vin": "1FTFW1E50NFA00002",
"score": 92.0,
"previousScore": 90.1,
"distanceM": 912300.0,
"scoredDays": 7,
"factors": [
{ "key": "timeOnRoad", "kind": "exposure", "days": 6 }
],
"connectionName": "Acme Fleet",
"groupNames": ["Night shift"],
"provider": "Geotab"
},
{
"vehicleId": "f8a0c256-7d9b-4e3a-b64c-9e5a3f7d1b42",
"name": "Unit 26",
"vin": "1FTFW1E50NFA00026",
"score": 91.2,
"previousScore": 90.4,
"distanceM": 791600.0,
"scoredDays": 7,
"factors": [],
"connectionName": "Acme Fleet",
"groupNames": ["South"],
"provider": "Geotab"
},
{
"vehicleId": "0a2c4e78-9f1d-4b5c-8e60-1b7d3a9f5c84",
"name": "Unit 31",
"vin": "1FTFW1E50NFA00031",
"score": 89.9,
"previousScore": null,
"distanceM": 432200.0,
"scoredDays": 5,
"factors": [
{ "key": "congestion", "kind": "environment", "days": 2 }
],
"connectionName": "Acme Fleet",
"groupNames": [],
"provider": "Geotab"
},
{
"vehicleId": "2c4e6a90-1b3f-4d7e-a082-3d9f5b1c7e06",
"name": "Unit 12",
"vin": "1FTFW1E50NFA00012",
"score": 88.7,
"previousScore": 87.2,
"distanceM": 876400.0,
"scoredDays": 7,
"factors": [
{ "key": "weather", "kind": "environment", "days": 3 }
],
"connectionName": "Acme Fleet",
"groupNames": ["North"],
"provider": "Geotab"
}
],
"notes": [
{ "section": "benchmark", "code": "BENCHMARK_SUPPRESSED" }
]
},
"next": null
}| Field | Description |
|---|---|
fleet | average and previousAverage of the scored vehicles, scoredVehicles (with a score in the period) and totalVehicles (in scope) |
trend | One entry per day of the period with that day's average score. average is null on a day without scores |
factors | Every risk factor and the number of vehicles it weighs on (vehiclesAffected), against the period before (previousVehiclesAffected). The factor with the most vehicles comes first |
lowest, highest | The five lowest and the five highest scoring vehicles, with the fields of a vehicle except connectionId, incidents, quartile, rankInConnection and vehiclesInConnection. Use the vehicles route for those |
A section that could not be read is null, and notes says why.
Export
GET /reports/safety-scores/export takes the parameters of the vehicles route except page and pageSize, and returns every matching vehicle in the order you asked for, with the same fields as a row of the vehicle table. When more than 20,000 vehicles match, truncated is true and the list stops at 20,000.
{
"status": 200,
"message": null,
"data": {
"asOf": "2026-10-31",
"window": {
"from": "2026-10-01",
"to": "2026-10-31",
"previousFrom": "2026-08-31",
"previousTo": "2026-09-30"
},
"rows": [
{
"vehicleId": "0b5f3c1e-7a42-4d8e-9c10-2f6a8b3d5e71",
"name": "Unit 02",
"vin": "1FTFW1E50NFA00002",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": ["Night shift"],
"provider": "Geotab",
"score": 91.2,
"previousScore": 89.7,
"distanceM": 3912400.0,
"scoredDays": 30,
"incidents": 0,
"quartile": 4,
"rankInConnection": 2,
"vehiclesInConnection": 48,
"factors": [
{ "key": "speeding", "kind": "behavior", "days": 6 },
{ "key": "timeOnRoad", "kind": "exposure", "days": 21 }
]
},
{
"vehicleId": "3d9a7e52-1c64-4b0f-8a37-5e2c9d1f6b84",
"name": "Unit 07",
"vin": "1FTFW1E50NFA00007",
"connectionId": "6f1c2b9e-3d4a-4c57-9b8e-0a1d2e3f4a5b",
"connectionName": "Acme Fleet",
"groupNames": ["North", "Night shift"],
"provider": "Geotab",
"score": 43.2,
"previousScore": 47.9,
"distanceM": 4217300.0,
"scoredDays": 30,
"incidents": 11,
"quartile": 1,
"rankInConnection": 48,
"vehiclesInConnection": 48,
"factors": [
{ "key": "tailgating", "kind": "behavior", "days": 22 },
{ "key": "hardBraking", "kind": "behavior", "days": 17 },
{ "key": "nightDriving", "kind": "exposure", "days": 12 }
]
}
],
"truncated": false,
"notes": []
},
"next": null
}Notes
notes is empty when everything was available. Otherwise each note says which part (section, the name of the response field) is affected and why (code):
code | Meaning |
|---|---|
NO_CONNECTIONS | Your account has no live connection |
NO_DATA | Your filters match no vehicle, or there is nothing to show |
NO_SCORES | No score has been computed yet for the period |
BENCHMARK_SUPPRESSED | Too few clients contribute for the benchmark to be shown |
TIMEOUT, SOURCE_ERROR | That part could not be read in time, or at all. The rest of the response is complete, and what depends on that part is null. For example, incidents is null when its note is on rows, and rankInConnection and vehiclesInConnection (driversInConnection) are null when the scores of your whole fleet could not be read. Call again after a minute |
RANKS_UNAVAILABLE | Ranks are left out because the fleet has more scored vehicles or drivers than one export holds (20,000) |
Good to know
- The answers are cached for up to 15 minutes, so a figure can lag the portal slightly.
- Scores are computed once a night.
scoredDaysis lower than the length of the period for a vehicle that was not scored every day. - Only vehicles have an incident count in these reports.
exportanddrivers/exportcan be called 1,000 times per API key per day (UTC), the two together. After that they answer429until the next day. Every export answer that is served, and the429, has the headersX-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset. A call that answers400, including one with an id that is not yours, is not counted and has no such headers.
Errors
A bad request answers 400 with a message, in the envelope of the other endpoints:
{
"status": 400,
"message": "'range' must be one of week, month or quarter.",
"data": null,
"next": null
}| Status | When |
|---|---|
400 | range is missing or not week, month or quarter; sort is not score, change, distance or name; scoreFrom or scoreTo is outside 0 to 100, or scoreFrom is above scoreTo; page or pageSize is out of range; or a connectionId, vehicle group, vehicle, driver group or driver is not yours (the answer is the same for one that does not exist, so ids cannot be probed). A value that cannot be read at all, such as page=abc, also answers 400, but with the framework's own error body instead of this envelope |
401 | The x-api-key is missing or invalid |
403 | The Analytics feature is not enabled on your account |
429 | export or drivers/export was called more than 1,000 times today with your API key. Try again after X-RateLimit-Reset |
Updated about 1 hour ago