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.
| Endpoint | Purpose |
|---|---|
GET /safety-events | Lists the events of a connection in a date range |
GET /safety-events/counts | Counts the events by event risk band |
GET /safety-events/types | Lists 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
| Parameter | Type | Required | Description |
|---|---|---|---|
from | date-time | Yes | Start 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 |
to | date-time | Yes | End 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 |
vehicleIds | array of UUID | No | Only events of these vehicles. Repeat the parameter for each id |
driverIds | array of UUID | No | Only events of these drivers |
eventType | string | No | Only this event type, for example Near Collision (see the types below) |
minIntensity | integer | No | Only events of at least this intensity |
minRiskScore | integer | No | Only events with an event risk of at least this band, 1 to 5 (4 returns High and Critical events) |
limit | integer | No | Events per page: 50 by default, at most 500 |
cursor | string | No | The 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
| Field | Type | Description |
|---|---|---|
id | string | Unique id of the safety event |
rawIncidentId | string, can be null | The id of the incident at the telematics provider |
connectionId | string | The connection the event belongs to |
startedAt / endedAt | date-time | When the event began and ended (UTC). endedAt can be null |
startLatitude / startLongitude | number | Where the event began |
endLatitude / endLongitude | number, can be null | Where the event ended |
type | string, can be null | The event type, for example Harsh Braking |
durationSeconds | integer | Duration of the event in seconds |
acceleration | number, can be null | Acceleration during the event, in G |
maxSpeed / minSpeed | number, can be null | Maximum and minimum speed during the event, in km/h |
updatedAt | date-time, can be null | When Manifold last updated the event, for example after validation |
cameraMedia | array, can be null | The 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) |
isProcessed | boolean | true when at least one incident of the provider on the event has a validation verdict (Accurate or Inaccurate) |
riskScore | integer, can be null | The 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 |
metadata | array, can be null | Further 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 |
next | string | The 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:
type | Meaning | data |
|---|---|---|
TspEvent | An incident the telematics provider reported. One entry per incident | IncidentType; TspIncidentTag, the validation result; TspIncidentIntensity (can be null) |
ManifoldEvent | An incident Manifold identified in the footage that the provider did not report. One entry per incident | IncidentType; ManifoldIncidentIntensity (can be null) |
TspIncidentTag is one of:
| Value | Meaning |
|---|---|
Accurate | The Validation Engine checked the incident and it is real |
Inaccurate | The Validation Engine checked the incident and it is not real |
Pending | Waiting for the Validation Engine |
NeverRated | The Validation Engine ended without a verdict |
NoVideo | There was no video to check, or the Validation Engine could not answer for it |
Excluded | Manifold does not validate this incident type |
Disabled | The 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
}| Field | Description |
|---|---|
total | All the events that match the filters: the five bands plus unscored plus other |
unscored | Events that have no event risk yet |
other | Events with a risk outside 1 to 5 (normally 0) |
counts | Always 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
}| Field | Description |
|---|---|
type | The name of the event type |
logo | The address of the logo of the type |
isExtended | Whether events of this type carry extended metadata |
Event types
The types you may see include:
| Event type | Description |
|---|---|
Harsh Braking | A sudden or aggressive braking event |
Hard Acceleration | A sudden or aggressive acceleration event |
Harsh Cornering | A sharp or aggressive turning event |
Harsh Motion | A sudden vehicle movement or jolt |
Speeding | The vehicle exceeded the applicable speed threshold or speed limit |
Tailgating | The vehicle followed another vehicle too closely |
Lane Departure | The vehicle drifted out of its lane unexpectedly |
Near Collision | A near miss with another object, vehicle or road user |
Accident | A detected collision or crash-related event |
Distracted Driving | The driver appears distracted or not focused on the road |
No Seatbelt | The driver is not wearing a seatbelt while the vehicle is moving |
Partial Seatbelt | The seatbelt appears to be worn incorrectly or only partially |
Camera Obstruction | The camera view is blocked |
Camera Misalignment | The camera angle is wrong and does not show the expected view |
Driver Missing | The interior camera does not show the driver when expected |
Tampering | The 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
| Endpoint | Returns |
|---|---|
GET /safety-events/{id}/thumbnails/{camPos}?format=img | The 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 |
| Parameter | Description |
|---|---|
id | The id of the safety event |
camPos | The camera position: in (interior), ex (exterior) or reex (rear exterior). Use the videoType of the event's cameraMedia |
format | Thumbnails only: img or gif (required) |
mode | Redirect (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
| Status | Meaning |
|---|---|
400 | The range is invalid or over 30 days, a parameter is invalid, or the Connection-Id is missing or is not one of yours |
401 | The x-api-key is missing or expired |
404 | The event does not exist on the connection (media endpoints) |
429 | Rate limited |
Updated 24 days ago