Incident Counts

Incident counts tell you how many incidents each behavioral incident type (Tailgating, Lane Departure, Distracted Driving and so on) had over the last 30, 60 or 90 days, how many of them are confirmed accurate, and how that compares with the period before. They are the figures of the portal's incident breakdown, for a vehicle, a driver, one connection or your whole account.

Speeding is not part of the breakdown: it has its own page in the portal.

All three need your x-api-key, and the Analytics feature on your account; without it they answer 403.

Query parameters

Example request

curl --request GET \
  --url "https://api.analytics.autos/vehicles/b7bad301-7572-4b8a-991b-65240d9d5784/incident-counts?period=30" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Example response

{
  "status": 200,
  "message": null,
  "data": {
    "subject": { "type": "vehicle", "id": "b7bad301-7572-4b8a-991b-65240d9d5784", "name": "Unit 14 (ABC1234)" },
    "period": { "days": 30, "from": "2026-09-22", "to": "2026-10-21" },
    "totals": {
      "byProvider": 86,
      "byManifold": 8,
      "totalAccurate": 26,
      "inaccurate": 66,
      "awaitingValidation": 2
    },
    "incidents": [
      { "incidentType": "Tailgating", "rate": 0.25, "change": -5,
        "byProvider": 68, "byManifold": 0, "totalAccurate": 17, "inaccurate": 49, "awaitingValidation": 2 },
      { "incidentType": "Lane Departure", "rate": 1.0, "change": -11,
        "byProvider": 0, "byManifold": 7, "totalAccurate": 7, "inaccurate": 0, "awaitingValidation": 0 },
      { "incidentType": "Distracted Driving", "rate": 0.1053, "change": -2,
        "byProvider": 18, "byManifold": 1, "totalAccurate": 2, "inaccurate": 17, "awaitingValidation": 0 }
    ]
  },
  "next": null
}

The example vehicle had incidents of three types, so the totals are the sum of its three rows (for example 68 + 0 + 18 = 86 incidents the provider reported). For GET /reports/incident-counts, subject.type is connection (with the connection's id and name) or client (your whole account, without an id).

Fields

A type that only had incidents in the previous period is not listed, so the totals and the changes cover the listed types.

Reading the figures

rate is not the accuracy of the provider's detection. rate is totalAccurate divided by all the incidents of the type, which means:

• the incidents still awaiting validation are in the denominator, so a type with many unvalidated incidents has a low rate that can still rise once they are validated;
• the incidents Manifold identified (byManifold) are in both the numerator and the denominator, although the provider did not report them.

To see how often the provider's incidents are right, use only the incidents that have a verdict. The provider's accurate incidents are totalAccurate - byManifold, so:

provider detection accuracy = (totalAccurate - byManifold) / (totalAccurate - byManifold + inaccurate)

For the three rows of the example:

change compares two periods of the same length. The current period ends today, today included. The previous period is the same number of days immediately before it. With period=30 on 2026-10-21 (the example):

For Tailgating change is -5: it has 17 accurate incidents in the current period and had 22 in the previous one. It is a difference in the number of accurate incidents, not a percentage.

Good to know

• A vehicle without a valid VIN has no counts: the response is empty, not an error.
• The counts of a vehicle or driver cover the incidents on your live connections only.
• The answer is cached for up to 15 minutes, so a figure can lag the portal slightly.
• GET /reports/incident-counts reads a lot of data for a large account. If the figures cannot be read within about 25 seconds, the endpoint answers 503 ("The incident counts are not available right now"). A failed attempt is remembered for a short time, so wait about a minute before you call again, and do not retry in a tight loop. The vehicle and driver counts read much less and are not affected (a vehicle answered in about 2 seconds on a large account). For a very large account the account-wide counts can keep answering 503; in that case request the counts per vehicle or per driver.

Errors