Safety Events

Safety events are the incidents recorded on your vehicles: harsh braking, speeding, tailgating, near collisions, camera alerts and so on, with their time and place, speed figures, risk rating and camera media.

EndpointPurpose
GET /safety-eventsLists the events of a connection in a date range
GET /safety-events/countsCounts the events by event risk band
GET /safety-events/typesLists the event types
GET /safety-events/{id}/thumbnails/{camPos}The thumbnail of an event's camera
GET /safety-events/{id}/videos/{camPos}The video of an event's camera
GET /safety-events/{id}/images/{camPos}The still image of an event's camera

Every endpoint needs your x-api-key and the Connection-Id header of one of your connections. A missing or foreign Connection-Id answers 400.

The API Reference lists every field and parameter.

List safety events

GET /safety-events

Returns the events of one connection between from and to, page by page.

Query parameters

ParameterTypeRequiredDescription
fromdate-timeYesStart of the range. Only the date counts: it is taken as 00:00:00 UTC at the start of that day. Example: 2026-10-01
todate-timeYesEnd of the range. Only the date counts (a time you add is ignored), and the whole of that day (UTC) is included. Example: 2026-10-12
vehicleIdsarray of UUIDNoOnly events of these vehicles. Repeat the parameter for each id
driverIdsarray of UUIDNoOnly events of these drivers
eventTypestringNoOnly this event type, for example Near Collision (see the types below)
minIntensityintegerNoOnly events of at least this intensity
minRiskScoreintegerNoOnly events with an event risk of at least this band, 1 to 5 (4 returns High and Critical events)
limitintegerNoEvents per page: 50 by default, at most 500
cursorstringNoThe next value of the previous page

The range may cover at most 30 days: to may be at most 30 days after from (from=2026-10-01 and to=2026-10-31 is allowed). A longer range answers 400 ("Date range should be less than 30 days"). to must not be before from.

The whole to day is included, as in /accidents and the Validation Engine reports.

Paging

When more events follow, the response carries next. Pass it as cursor to read the next page; stop when next is null. A page can hold fewer events than limit even when next is set (events that are not returned, see Validation results, are removed from the page after it is read), so always follow next until it is null rather than stopping at a short page.

Example request

curl --request GET \
  --url "https://api.analytics.autos/safety-events?from=2026-10-01&to=2026-10-12&minRiskScore=4&eventType=Tailgating&limit=1" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Example response

{
  "status": 200,
  "message": null,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "rawIncidentId": "b2f6a1d0-5f1c-4c52-9d0e-0a7a5b5f2c11",
      "connectionId": "4c540ad6-3e76-427c-95e8-72ce794b34de",
      "startedAt": "2026-10-09T16:12:52.505Z",
      "endedAt": "2026-10-09T16:12:54.505Z",
      "startLatitude": 43.6532,
      "startLongitude": -79.3832,
      "endLatitude": 43.6535,
      "endLongitude": -79.3829,
      "type": "Tailgating",
      "durationSeconds": 2,
      "acceleration": 5.2,
      "maxSpeed": 80.0,
      "minSpeed": 30.0,
      "updatedAt": "2026-10-09T16:20:03.112Z",
      "cameraMedia": [
        { "id": "7f0f9d1e-2c64-4f55-8a0a-6d3a4e6d0b41", "videoType": "ex", "mediaType": "Video" },
        { "id": "0c8b5b4a-9c0a-4d2f-a0f6-3f4a0e1a7c52", "videoType": "in", "mediaType": "Video" }
      ],
      "isProcessed": true,
      "riskScore": 4,
      "metadata": [
        { "type": "TspEvent", "data": [
          { "key": "TspIncidentIntensity", "value": 2 },
          { "key": "TspIncidentTag", "value": "Accurate" },
          { "key": "IncidentType", "value": "Tailgating" }
        ] },
        { "type": "ManifoldEvent", "data": [
          { "key": "ManifoldIncidentIntensity", "value": 1 },
          { "key": "IncidentType", "value": "Distracted Driving" }
        ] }
      ]
    }
  ],
  "next": "eyJvZmZzZXQiOjEwMH0"
}

Fields

FieldTypeDescription
idstringUnique id of the safety event
rawIncidentIdstring, can be nullThe id of the incident at the telematics provider
connectionIdstringThe connection the event belongs to
startedAt / endedAtdate-timeWhen the event began and ended (UTC). endedAt can be null
startLatitude / startLongitudenumberWhere the event began
endLatitude / endLongitudenumber, can be nullWhere the event ended
typestring, can be nullThe event type, for example Harsh Braking
durationSecondsintegerDuration of the event in seconds
accelerationnumber, can be nullAcceleration during the event, in G
maxSpeed / minSpeednumber, can be nullMaximum and minimum speed during the event, in km/h
updatedAtdate-time, can be nullWhen Manifold last updated the event, for example after validation
cameraMediaarray, can be nullThe camera media of the event: id, videoType (the camera position to use in the media routes: in interior, ex exterior, reex rear exterior) and mediaType (Video or Image)
isProcessedbooleantrue when at least one incident of the provider on the event has a validation verdict (Accurate or Inaccurate)
riskScoreinteger, can be nullThe event risk: 1 Very Low, 2 Low, 3 Medium, 4 High, 5 Critical. null until the event has been risk scored. This is a risk band, not a 0 to 100 score
metadataarray, can be nullFurther information of the event, as type and a list of data objects (key and value). It holds the validation result of each incident of the event: see Validation results
nextstringThe cursor of the next page; null on the last page

Validation results

The validation result of each incident of an event is in its metadata:

typeMeaningdata
TspEventAn incident the telematics provider reported. One entry per incidentIncidentType; TspIncidentTag, the validation result; TspIncidentIntensity (can be null)
ManifoldEventAn incident Manifold identified in the footage that the provider did not report. One entry per incidentIncidentType; ManifoldIncidentIntensity (can be null)

TspIncidentTag is one of:

ValueMeaning
AccurateThe Validation Engine checked the incident and it is real
InaccurateThe Validation Engine checked the incident and it is not real
PendingWaiting for the Validation Engine
NeverRatedThe Validation Engine ended without a verdict
NoVideoThere was no video to check, or the Validation Engine could not answer for it
ExcludedManifold does not validate this incident type
DisabledThe connection is not enrolled in the Validation Engine

An incident Manifold identified (ManifoldEvent) is confirmed by definition and carries no tag.

Only events with at least one verdict are returned. GET /safety-events returns an event when at least one of its provider incidents is Accurate or Inaccurate. An event whose incidents are all still Pending, NeverRated, NoVideo, Excluded or Disabled is not returned. The other incidents of a returned event are listed with their own tag, so you can see Pending or NeverRated next to a verdict. To see how many incidents are still awaiting validation, use the awaitingValidation count of the Incident Counts; the figures per day are in the Validation Engine Reports.

Count safety events by risk

GET /safety-events/counts

Counts the events that match the filters of the list, by event risk band. It takes the same from, to, vehicleIds, driverIds, eventType and minIntensity parameters (and the same 30-day range, and the whole to day is included).

curl --request GET \
  --url "https://api.analytics.autos/safety-events/counts?from=2026-10-01&to=2026-10-12" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'
{
  "status": 200,
  "message": null,
  "data": {
    "total": 1250,
    "unscored": 40,
    "other": 0,
    "counts": [
      { "eventRisk": 1, "label": "Very Low", "count": 700 },
      { "eventRisk": 2, "label": "Low", "count": 300 },
      { "eventRisk": 3, "label": "Medium", "count": 150 },
      { "eventRisk": 4, "label": "High", "count": 45 },
      { "eventRisk": 5, "label": "Critical", "count": 15 }
    ]
  },
  "next": null
}
FieldDescription
totalAll the events that match the filters: the five bands plus unscored plus other
unscoredEvents that have no event risk yet
otherEvents with a risk outside 1 to 5 (normally 0)
countsAlways five entries, for the bands 1 to 5 in order, with the band's label and its count

List safety event types

GET /safety-events/types

Returns the event types, each with the logo Manifold shows for it. Use a type as the eventType of the list.

curl --request GET \
  --url "https://api.analytics.autos/safety-events/types" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'
{
  "status": 200,
  "message": null,
  "data": [
    { "type": "Harsh Braking", "logo": "https://cdn.example.com/incident-types/harsh-braking.svg", "isExtended": true },
    { "type": "Near Collision", "logo": "https://cdn.example.com/incident-types/near-collision.svg", "isExtended": false }
  ],
  "next": null
}
FieldDescription
typeThe name of the event type
logoThe address of the logo of the type
isExtendedWhether events of this type carry extended metadata

Event types

The types you may see include:

Event typeDescription
Harsh BrakingA sudden or aggressive braking event
Hard AccelerationA sudden or aggressive acceleration event
Harsh CorneringA sharp or aggressive turning event
Harsh MotionA sudden vehicle movement or jolt
SpeedingThe vehicle exceeded the applicable speed threshold or speed limit
TailgatingThe vehicle followed another vehicle too closely
Lane DepartureThe vehicle drifted out of its lane unexpectedly
Near CollisionA near miss with another object, vehicle or road user
AccidentA detected collision or crash-related event
Distracted DrivingThe driver appears distracted or not focused on the road
No SeatbeltThe driver is not wearing a seatbelt while the vehicle is moving
Partial SeatbeltThe seatbelt appears to be worn incorrectly or only partially
Camera ObstructionThe camera view is blocked
Camera MisalignmentThe camera angle is wrong and does not show the expected view
Driver MissingThe interior camera does not show the driver when expected
TamperingThe camera or device appears to have been blocked, moved, covered or interfered with

The list your account returns is the authority: call GET /safety-events/types for the types of a connection.

Media: thumbnail, video and image

EndpointReturns
GET /safety-events/{id}/thumbnails/{camPos}?format=imgThe thumbnail image (format=gif returns an animated GIF)
GET /safety-events/{id}/videos/{camPos}The video
GET /safety-events/{id}/images/{camPos}The still image
ParameterDescription
idThe id of the safety event
camPosThe camera position: in (interior), ex (exterior) or reex (rear exterior). Use the videoType of the event's cameraMedia
formatThumbnails only: img or gif (required)
modeRedirect (default) answers with a redirect to a temporary signed address; Url answers with the address itself

The signed address expires after a short time, so request it when you need it rather than storing it. An id that is not an event of the connection answers 404.

curl --request GET \
  --url "https://api.analytics.autos/safety-events/123e4567-e89b-12d3-a456-426614174000/thumbnails/in?format=img&mode=Url" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Errors

StatusMeaning
400The range is invalid or over 30 days, a parameter is invalid, or the Connection-Id is missing or is not one of yours
401The x-api-key is missing or expired
404The event does not exist on the connection (media endpoints)
429Rate limited

Did this page help you?