--- title: "Get Safety Events Stream" method: GET path: "/safety-events/stream" tags: ["Safety"] --- # Get Safety Events Stream `GET /safety-events/stream` ## Request - Base URL: `https://api.samsara.com` - URL: `https://api.samsara.com/safety-events/stream` - Auth: HTTP bearer This endpoint will return all safety events associated with your organization based on the parameters passed in. To get core endpoint data, select Read Safety Events & Scores under the Safety & Cameras category when creating or editing an API token. Read Camera Media permissions required to get Safety Event video media via this endpoint. If you include an endTime, the endpoint will return data up until that point. If you do not include an endTime, you can continue to poll the API real-time with the pagination cursor that gets returned on every call. Results are paginated. Rate limit: 5 requests/sec (learn more about rate limits here). To use this endpoint, select **Read Safety Events & Scores** under the Safety & Cameras category when creating or editing an API token. Learn More. **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team. ## Query parameters - `startTime` string, required - `endTime` string - `queryByTimeField` 'updatedAtTime' | 'createdAtTime' - `assetIds` string[] - `driverIds` string[] - `tagIds` string[] - `assignedCoaches` string[] - `behaviorLabels` string[] - `eventStates` string[] - `includeAsset` boolean - `includeDriver` boolean - `includeVgOnlyEvents` boolean - `after` string ## Response `200` OK response. - SafetyEventsV2GetSafetyEventsV2StreamResponseBody - `data` SafetyEventV2ObjectResponseBody[], required: List of safety event objects. - `asset` SafetyEventV2AssetObjectResponseBody, required: Asset that the safety event is tied to. - `attributes` GoaAttributeTinyResponseBody[]: Attributes for the asset associated with the safety event. Only returns when `includeAsset` is set to `true`. - `dateValues` string[]: List of date values associated with the attribute (RFC 3339 full-date format: YYYY-MM-DD). - `id` string: Id of the attribute - `name` string: Name of the attribute - `numberValues` number[]: List of number values associated with the attribute - `stringValues` string[]: List of string values associated with the attribute. - `externalIds` object: A map of external ids - `id` string, required: Unique ID for the asset object that is reporting the safety event. - `name` string: Name for the asset object that is reporting the safety event. Only returns when `includeAsset` is set to `true`. - `tags` GoaTagTinyResponseResponseBody[]: Tags for the asset associated with the safety event. Only returns when `includeAsset` is set to `true`. - `id` string, required: ID of the tag - `name` string, required: Name of the tag. - `parentTagId` string: If this tag is part a hierarchical tag tree, this is the ID of the parent tag, otherwise this will be omitted. - `type` 'uncategorized' | 'trailer' | 'equipment' | 'unpowered' | 'vehicle': Type for the asset object that is reporting the location. Only returns when `includeAsset` is set to `true`. Valid values: `uncategorized`, `trailer`, `equipment`, `unpowered`, `vehicle` - `vin` string: VIN for the asset object. Only returns when `includeAsset` is set to `true`. - `assignedCoach` string: Unique user ID for the assigned coach. - `behaviorLabels` SafetyEventV2BehaviorLabelsResponseBody[], required: The most up-to-date behavior labels associated with the safety event. These labels can be updated by Safety Admins. - `label` 'Acceleration' | 'AggressiveDriving' | 'BluetoothHeadset' | 'Braking' | 'ContextConstructionOrWorkZone' | 'ContextSnowyOrIcy' | 'ContextVulnerableRoadUser' | 'ContextWet' | 'Crash' | 'DefensiveDriving' | 'DidNotYield' | 'Drinking' | 'Drowsy' | 'Eating' | 'EatingDrinking' | 'EdgeDistractedDriving' | 'EdgeRailroadCrossingViolation' | 'FollowingDistance' | 'FollowingDistanceModerate' | 'FollowingDistanceSevere' | 'ForwardCollisionWarning' | 'GenericDistraction' | 'GenericTailgating' | 'HarshImpact' | 'HarshTurn' | 'HeavySpeeding' | 'HighSpeedSuddenDisconnect' | 'HosViolation' | 'Idling' | 'ImproperEgress' | 'Invalid' | 'LaneDeparture' | 'LateResponse' | 'LeftTurn' | 'LightSpeeding' | 'MaxSpeed' | 'MobileUsage' | 'ModerateSpeeding' | 'NearCollison' | 'NearPedestrianCollision' | 'NoSeatbelt' | 'ObstructedCamera' | 'OperationalEvent' | 'OtherViolation' | 'Passenger' | 'PolicyViolationMask' | 'ProtectiveEquipment' | 'ProximityWarning' | 'RanRedLight' | 'RearCollisionWarning' | 'Reversing' | 'RollingStop' | 'RolloverProtection' | 'SevereSpeeding' | 'Smoking' | 'Speeding' | 'UTurn' | 'UnsafeManeuver' | 'UnsafeParking' | 'VehicleInBlindSpotWarning' | 'VulnerableRoadUserCollisionWarning' | 'YawControl': The label associated with the safety event. Labels can be updated by Safety Admins, if a label is removed from a safety event it will be removed from this list. Valid values: `Acceleration`, `AggressiveDriving`, `BluetoothHeadset`, `Braking`, `ContextConstructionOrWorkZone`, `ContextSnowyOrIcy`, `ContextVulnerableRoadUser`, `ContextWet`, `Crash`, `DefensiveDriving`, `DidNotYield`, `Drinking`, `Drowsy`, `Eating`, `EatingDrinking`, `EdgeDistractedDriving`, `EdgeRailroadCrossingViolation`, `FollowingDistance`, `FollowingDistanceModerate`, `FollowingDistanceSevere`, `ForwardCollisionWarning`, `GenericDistraction`, `GenericTailgating`, `HarshImpact`, `HarshTurn`, `HeavySpeeding`, `HighSpeedSuddenDisconnect`, `HosViolation`, `Idling`, `ImproperEgress`, `Invalid`, `LaneDeparture`, `LateResponse`, `LeftTurn`, `LightSpeeding`, `MaxSpeed`, `MobileUsage`, `ModerateSpeeding`, `NearCollison`, `NearPedestrianCollision`, `NoSeatbelt`, `ObstructedCamera`, `OperationalEvent`, `OtherViolation`, `Passenger`, `PolicyViolationMask`, `ProtectiveEquipment`, `ProximityWarning`, `RanRedLight`, `RearCollisionWarning`, `Reversing`, `RollingStop`, `RolloverProtection`, `SevereSpeeding`, `Smoking`, `Speeding`, `UTurn`, `UnsafeManeuver`, `UnsafeParking`, `VehicleInBlindSpotWarning`, `VulnerableRoadUserCollisionWarning`, `YawControl` - `source` 'automated' | 'userGenerated': The source of the label associated with the safety event. Valid values: `automated`, `userGenerated` - `contextLabels` SafetyEventV2ContextLabelsResponseBody[], required: The most up-to-date context labels associated with the safety event. AI generated labels can be updated by Safety Admins. - `authorId` string, required: The user ID associated with the user who created the context label. A value of 0 indicates the label is auto-generated. - `createdAtTime` string, required: Time the context label was created. - `name` string, required: Name of the context label - `createdAtTime` string, required: UTC time the Safety Event was created in Samsara in RFC 3339 format. This field may differ from when the event was detected (`startMs`). - `detectedStreams` SafetyEventV2MediaResponseBody[]: Camera streams that detected the safety event. - `auxcamSerial` string: The serial number of the auxiliary camera device. - `cameraRole` 'leftMirrorMount' | 'leftSide' | 'rightMirrorMount' | 'rightSide' | 'rearHigh' | 'rearBumper' | 'inCab' | 'front' | 'hopper' | 'other1' | 'other2' | 'other3' | 'other4' | 'leftBev' | 'rightBev' | 'rearBev' | 'frontBev' | 'otherBev' | 'bevNotUsed': The currently assigned role name of the camera. May change if camera role settings are updated. Valid values: `leftMirrorMount`, `leftSide`, `rightMirrorMount`, `rightSide`, `rearHigh`, `rearBumper`, `inCab`, `front`, `hopper`, `other1`, `other2`, `other3`, `other4`, `leftBev`, `rightBev`, `rearBev`, `frontBev`, `otherBev`, `bevNotUsed` - `input` 'dashcamRoadFacing' | 'dashcamDriverFacing' | 'analog1' | 'analog2' | 'analog3' | 'analog4', required: The media input type of the camera. Valid values: `dashcamRoadFacing`, `dashcamDriverFacing`, `analog1`, `analog2`, `analog3`, `analog4` - `url` string, required: URL to download the media asset. - `dismissalReason` SafetyEventDismissalReasonResponseBody: Dismissal reason associated with a Safety Event. - `code` 'incorrect' | 'minorEvent' | 'other': The dismissal reason code associated with the event. Valid values: `incorrect`, `minorEvent`, `other` - `comment` string: The dismissal reason comment associated with the event. - `driver` SafetyEventV2DriverObjectResponseBody, required: Driver that is assigned to the safety event. - `attributes` GoaAttributeTinyResponseBody[]: Attributes for the driver associated with the safety event. Only returns when `includeDriver` is set to `true`. - `dateValues` string[]: List of date values associated with the attribute (RFC 3339 full-date format: YYYY-MM-DD). - `id` string: Id of the attribute - `name` string: Name of the attribute - `numberValues` number[]: List of number values associated with the attribute - `stringValues` string[]: List of string values associated with the attribute. - `externalIds` object: A map of external ids - `id` string, required: Unique ID for the driver object that is assigned to the safety event. - `name` string: Name of the driver. Only returns when `includeDriver` is set to `true`. - `tags` GoaTagTinyResponseResponseBody[]: Tags for the driver associated with the safety event. Only returns when `includeDriver` is set to `true`. - `id` string, required: ID of the tag - `name` string, required: Name of the tag. - `parentTagId` string: If this tag is part a hierarchical tag tree, this is the ID of the parent tag, otherwise this will be omitted. - `endMs` string, required: UTC time the Safety Event detection ended in RFC 3339 format. - `eventState` 'unknown' | 'needsReview' | 'reviewed' | 'needsCoaching' | 'coached' | 'dismissed' | 'needsRecognition' | 'recognized', required: The current state of the Safety Event. Valid values: `unknown`, `needsReview`, `reviewed`, `needsCoaching`, `coached`, `dismissed`, `needsRecognition`, `recognized` - `id` string, required: The unique Samsara ID (uuid) of the safety event. - `inboxEventUrl` string, required: A link to the Safety Event review page for the associated event. - `incidentReportUrl` string, required: If a harsh event, returns the URL of the associated incident report page. If a speeding event, returns the URL of the associated speeding report page. - `location` LocationResponseResponseBody, required: Location object. - `accuracyMeters` number, double: Radial accuracy of gps location in meters. This will only return if strong GPS is not available. - `address` AddressResponseResponseBody: Closest address that the GPS latitude and longitude match to. - `city` string: The name of the city - `country` string: The country - `neighborhood` string: The name of the neighborhood if one exists - `pointOfInterest` string: Point that may be of interest to the user - `postalCode` string: The zip code - `state` string: The name of the state - `street` string: The street name - `streetNumber` string: Street number of the address - `geofence` GeofenceResponseResponseBody: Closest geofence based on 1000 meter radial search. - `externalIds` object: A map of external ids - `id` string: Unique ID of the geofence object. - `headingDegrees` integer, required: Heading of the asset in degrees. May be 0 if the asset is not moving. - `latitude` number, double, required: Latitude of the location of the asset. - `longitude` number, double, required: Longitude of the location of the asset. - `maxAccelerationGForce` number, double, required: The maximum acceleration value as a multiplier on the force of gravity (g). - `media` SafetyEventV2MediaResponseBody[]: Media assets available for the safety event. - `auxcamSerial` string: The serial number of the auxiliary camera device. - `cameraRole` 'leftMirrorMount' | 'leftSide' | 'rightMirrorMount' | 'rightSide' | 'rearHigh' | 'rearBumper' | 'inCab' | 'front' | 'hopper' | 'other1' | 'other2' | 'other3' | 'other4' | 'leftBev' | 'rightBev' | 'rearBev' | 'frontBev' | 'otherBev' | 'bevNotUsed': The currently assigned role name of the camera. May change if camera role settings are updated. Valid values: `leftMirrorMount`, `leftSide`, `rightMirrorMount`, `rightSide`, `rearHigh`, `rearBumper`, `inCab`, `front`, `hopper`, `other1`, `other2`, `other3`, `other4`, `leftBev`, `rightBev`, `rearBev`, `frontBev`, `otherBev`, `bevNotUsed` - `input` 'dashcamRoadFacing' | 'dashcamDriverFacing' | 'analog1' | 'analog2' | 'analog3' | 'analog4', required: The media input type of the camera. Valid values: `dashcamRoadFacing`, `dashcamDriverFacing`, `analog1`, `analog2`, `analog3`, `analog4` - `url` string, required: URL to download the media asset. - `speedingMetadata` SafetyEventSpeedingMetadataResponseBody: Speeding data associated with the event. Only returned for speeding related events. - `maxSpeedKilometersPerHour` integer, required: The max speed exceeded during the event, provided in kilometers per hour. - `postedSpeedLimitKilometersPerHour` integer, required: The posted speed limit associated with the event, provided in kilometers per hour. - `startMs` string, required: UTC time the Safety Event was detected in RFC 3339 format. - `tripEndTime` string: UTC time the trip ended in RFC 3339 format. Null when Safety Event occurs off-trip or the trip is ongoing. - `tripStartTime` string: UTC time the trip started in RFC 3339 format. Null when Safety Event occurs off-trip. - `updatedAtTime` string, required: UTC time the Safety Event was updated in Samsara in RFC 3339 format. - `updatedByUserId` string: The user ID associated with the user who made the event state change. Only returned if the event state changes. - `pagination` GoaPaginationResponseResponseBody, required: Pagination parameters. - `endCursor` string, required: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view. - `hasNextPage` boolean, required: True if there are more pages of results immediately available after this endCursor. ## Other responses - `401`: Unauthorized response. - `404`: Not Found response. - `405`: Method Not Allowed response. - `413`: Content Too Large response. - `429`: Too Many Requests response. - `500`: Internal Server Error response. - `501`: Not Implemented response. - `502`: Bad Gateway response. - `503`: Service Unavailable response. - `504`: Gateway Timeout response. - `default`: Bad Request response. --- [API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)