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.

EndpointWhat it returns
GET /reports/safety-scores/summaryThe 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/vehiclesThe 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/exportThe same vehicles, all in one answer (at most 20,000)
GET /reports/safety-scores/driversThe 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/exportThe 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

ParameterTypeRoutesDescription
rangestringallRequired. 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
connectionIdUUIDallOnly the vehicles of this connection. One of your own connections, otherwise 400
vehicleGroupIdsarraysummary, vehicles, exportOnly the vehicles of these vehicle groups. Repeat the parameter for each group; a vehicle that belongs to any of the groups is included
vehicleIdsarraysummary, vehicles, exportOnly these vehicles. Repeat the parameter for each vehicle
driverGroupIdsarraydrivers, drivers/exportOnly the drivers of these driver groups. Repeat the parameter for each group; a driver that belongs to any of the groups is included
driverIdsarraydrivers, drivers/exportOnly these drivers. Repeat the parameter for each driver
factorstringvehicles, export, drivers, drivers/exportOnly 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, scoreTonumbervehicles, export, drivers, drivers/exportOnly scores from scoreFrom (included) up to scoreTo (not included; 100 includes 100). Between 0 and 100, and scoreFrom not above scoreTo
searchstringvehicles, export, drivers, drivers/exportOnly vehicles whose name or VIN, or drivers whose name or employee number, contains the text. Ignored when shorter than two characters
sortstringvehicles, export, drivers, drivers/exportscore (default), change (the change from the previous score), distance or name
descbooleanvehicles, export, drivers, drivers/exportSort from high to low. The default, false, sorts from low to high (with sort=score, the lowest scores first)
pageintegervehicles, driversThe page, starting at 1 (default 1)
pageSizeintegervehicles, driversVehicles 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

FieldDescription
vehicleIdThe vehicle's Manifold id
nameThe vehicle's name, or its VIN when it has no name
vinThe vehicle identification number
connectionId, connectionNameThe connection the vehicle's rank is taken in, and its name
groupNamesThe vehicle groups the vehicle belongs to
providerThe telematics provider of the connection
scoreThe mean daily score over the period, 0 to 100. High is safe
previousScoreThe 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
distanceMMetres driven in the period
scoredDaysDays of the period on which the vehicle was scored
incidentsThe 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)
quartileThe band the score falls in, from 1 (the lowest scores, the riskiest quarter) to 4 (the highest, the safest). See Quartiles and bands
rankInConnectionThe 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
vehiclesInConnectionThe number of scored vehicles rankInConnection is out of
factorsThe 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

FieldDescription
asOfThe latest day the scores cover (UTC). The period ends on this day
windowfrom and to (the period, both days included), and previousFrom and previousTo (the period before)
totalThe vehicles that match all your filters, before paging
rowsThe requested page of vehicles
histogramThe score distribution in twenty 5-point bins: [0,5), [5,10) and so on up to [95,100]
fineHistogramThe same distribution in one hundred 1-point bins, [0,1) up to [99,100]
bandCountsThe vehicles in each of the four bands, the lowest scores first
fleetAverageThe mean score of the vehicles the distribution covers
benchmarkaverage: 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
bandsThe cut points that split scores into four bands, and their source
notesExplains 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:

quartileScoresMeaning
1below 60The lowest scores: the riskiest quarter
260 up to, not including, 75
375 up to, not including, 85
485 to 100The 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:

  1. Call GET /reports/safety-scores/vehicles with the range and the connection, vehicle group or vehicle filters you want. A small pageSize is enough: the distribution does not depend on the page.
  2. Draw one bar for each entry of fineHistogram (or histogram for coarser bars): from and to are the bar's score range and count its height.
  3. 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.
  4. Mark fleetAverage and, when it is there, benchmark.average.
  5. 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 driverDescription
driverIdThe driver's Manifold id
nameThe driver's name, or Driver when it is blank
employeeNumberThe driver's employee number
currentVehiclevehicleId 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
currentVehicleSourceassigned or lastDriven; null exactly when currentVehicle is
connectionId, connectionName, provider, groupNamesThe connection the driver's rank is taken in, its name and telematics provider, and the driver's groups
score, previousScoreThe 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
distanceMMetres driven in the period. null when the driver's provider does not attribute trips to drivers: the distance is unknown, not zero
scoredDays, previousScoredDaysDays of the period, and of the period before, on which the driver was scored. A change that rests on few previousScoredDays is weak
quartileThe 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, driversInConnectionThe 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
factorsThe 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
}
FieldDescription
fleetaverage and previousAverage of the scored vehicles, scoredVehicles (with a score in the period) and totalVehicles (in scope)
trendOne entry per day of the period with that day's average score. average is null on a day without scores
factorsEvery 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, highestThe 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):

codeMeaning
NO_CONNECTIONSYour account has no live connection
NO_DATAYour filters match no vehicle, or there is nothing to show
NO_SCORESNo score has been computed yet for the period
BENCHMARK_SUPPRESSEDToo few clients contribute for the benchmark to be shown
TIMEOUT, SOURCE_ERRORThat 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_UNAVAILABLERanks 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. scoredDays is 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.
  • export and drivers/export can be called 1,000 times per API key per day (UTC), the two together. After that they answer 429 until the next day. Every export answer that is served, and the 429, has the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A call that answers 400, 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
}
StatusWhen
400range 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
401The x-api-key is missing or invalid
403The Analytics feature is not enabled on your account
429export or drivers/export was called more than 1,000 times today with your API key. Try again after X-RateLimit-Reset

Did this page help you?