> ## Documentation Index > Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt > Use this file to discover all available pages before exploring further. # List Safety Events > List all safety events detected by the provider. ## OpenAPI ````yaml GET /safety/events openapi: 3.1.0 info: title: Terminal Telematics API description: >- Terminal is a unified API that makes it easy to integrate with the leading telematics service providers. version: '0.0' contact: name: Terminal email: connect@withterminal.com url: https://www.withterminal.com servers: - url: https://api.withterminal.com/tsp/v1 description: Production - url: https://api.sandbox.withterminal.com/tsp/v1 description: Sandbox security: - Authorization: [] tags: - name: Authentication - name: Connections - name: Data Management - name: Drivers - name: Groups - name: Hours of Service - name: IFTA - name: Issues - name: Link - name: Providers - name: Safety - name: Trailers - name: Vehicles - name: Vehicle Utilization - name: Webhook Events paths: /safety/events: parameters: [] get: tags: - Safety summary: List Safety Events description: List all safety events detected by the provider. operationId: listSafetyEvents parameters: - name: Connection-Token in: header required: true schema: type: string example: con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4 pattern: ^con_tkn_\S+$ description: >- The token returned when a user authenticated their account. This authorizes access to a specific account. - name: cursor in: query schema: type: string format: cursor example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw description: Pagination cursor to start requests from - name: limit in: query required: false schema: type: integer description: The maximum number of results to return in a page. - name: modifiedAfter in: query required: false schema: type: string format: date-time example: '2021-01-06T03:24:53.000Z' description: Only include records that were last modified after a provided date. - name: modifiedBefore in: query required: false schema: type: string format: date-time example: '2021-01-06T03:24:53.000Z' description: Only include records that were last modified before a provided date. - schema: title: ISODateTime type: string format: date-time example: '2021-01-06T03:24:53.000Z' description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date' in: query name: startedAfter description: Only include records of statuses that started after a provided date. - schema: title: ISODateTime type: string format: date-time example: '2021-01-06T03:24:53.000Z' description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date' in: query name: startedBefore description: >- Only include records of statuses that started before a provided date. - name: driverIds in: query required: false schema: type: string pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}(\s*,\s*drv_[0-9A-HJKMNP-TV-Z]{26})*$ description: >- Comma separated list of driver IDs to filter for. Can filter up to 50 drivers at a time. Each ID must use the `drv_` prefix. - name: vehicleIds in: query required: false schema: type: string pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}(\s*,\s*vcl_[0-9A-HJKMNP-TV-Z]{26})*$ description: >- Comma separated list of vehicle IDs to filter for. Can filter up to 50 vehicles at a time. Each ID must use the `vcl_` prefix. - schema: type: string enum: - vehicle - driver - driver,vehicle - vehicle,driver in: query name: expand description: Expand resources in the returned response - name: raw in: query required: false schema: type: boolean description: >- Include raw responses used to normalize model. Used for debugging or accessing unique properties that are not unified. responses: '200': description: OK content: application/json: schema: type: object properties: results: type: array items: type: object title: Safety Event additionalProperties: false x-model-category: historical properties: id: title: SafetyEventId type: string format: ulid pattern: ^sft_evt_[0-9A-HJKMNP-TV-Z]{26}$ example: sft_evt_01D8ZQFGHVJ858NBF2Q7DV9MNC sourceId: title: SourceId type: string example: '123456789' description: >- The ID used to represent the entity in the source system. provider: title: Provider Code type: string example: geotab description: >- Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers). type: title: SafetyEventType type: string enum: - harsh_brake - harsh_acceleration - harsh_turn - speeding - crash - near_crash - tailgating - cell_phone - distracted - drowsiness - smoking - seat_belt_violation - stop_sign_violation - red_light_violation - unsafe_lane_change - camera_obstruction - eating_and_drinking - rolling_stop - unsafe_parking sourceType: type: string example: HARD_CORE_BRAKING_MESSAGE description: >- The original event type as defined by the telematics provider's system driver: example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC oneOf: - title: DriverId description: Unique identifier for the driver in Terminal. type: string format: ulid pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}$ example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC - title: Expanded Driver type: object properties: id: title: DriverId description: >- Unique identifier for the driver in Terminal. type: string format: ulid pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}$ example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC required: - id description: >- Entities in Terminal are expandable. Using the `expand` query parameter you can choose to ingest just an ID or the full entity details. vehicle: description: >- The ID of the vehicle that was involved in the event. example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC oneOf: - title: VehicleId description: Unique identifier for the vehicle in Terminal. type: string format: ulid pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}$ example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC - title: Expanded Vehicle type: object properties: id: title: VehicleId description: >- Unique identifier for the vehicle in Terminal. type: string format: ulid pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}$ example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC required: - id startedAt: title: ISODateTime type: string format: date-time example: '2021-01-06T03:24:53.000Z' description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date' startLocation: title: Coordinates type: object properties: longitude: type: number example: -122.4194155 latitude: type: number example: 37.7749295 required: - longitude - latitude endedAt: title: ISODateTime type: string format: date-time example: '2021-01-06T03:24:53.000Z' description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date' endLocation: title: Coordinates type: object properties: longitude: type: number example: -122.4194155 latitude: type: number example: 37.7749295 required: - longitude - latitude stats: type: object properties: maximumSpeed: title: Speed In KPH type: number description: Speed in KPH rounded to 2 decimal places. example: 95.33 averageSpeed: title: Speed In KPH type: number description: Speed in KPH rounded to 2 decimal places. example: 95.33 roadSpeedLimit: title: Speed In KPH type: number description: Speed in KPH rounded to 2 decimal places. example: 95.33 gForceForwardBackward: description: >- The acceleration/breaking force as a factor of gravity (g). title: G-Force type: number example: 1 gForceSideToSide: description: >- The cornering (lateral) acceleration as a factor of gravity (g). title: G-Force type: number example: 1 heading: title: Heading In Degrees type: number description: Heading in degrees example: 25 cameraMedia: title: Camera Media Reference type: object properties: frontFacing: description: The front facing camera media. title: Camera Media Reference type: object properties: available: type: boolean description: >- Indicates whether the camera media file is available for retrieval. example: true sourceId: type: string description: >- The identifier for the camera media file in the source system. example: '12345' required: - available rearFacing: description: The rear facing camera media. title: Camera Media Reference type: object properties: available: type: boolean description: >- Indicates whether the camera media file is available for retrieval. example: true sourceId: type: string description: >- The identifier for the camera media file in the source system. example: '12345' required: - available extensions: type: object description: >- Includes data enriched via third-party vendors. See [Extensions](/terminal-platform/extensions) properties: here: description: Data obtained from the HERE platform. title: Here Safety Event Extension type: object properties: speedLimit: title: Speed In KPH type: number description: Speed in KPH rounded to 2 decimal places. example: 95.33 speedLimitSource: title: Speed Limit Source type: string enum: - posted - derived description: >- Source for speed limit obtained from the HERE platform. example: posted truckSpeedLimit: title: Speed In KPH type: number description: Speed in KPH rounded to 2 decimal places. example: 95.33 roadName: type: string description: >- Name of the road obtained from the HERE platform. example: John St linkAttributes: type: object description: >- Additional road attributes from HERE platform properties: countryCode: type: string description: ISO country code of the road location vehicleTypes: type: string description: Types of vehicles allowed isUrban: type: string description: >- Indicates if the road is in an urban area transportVerified: type: string description: >- Indicates if transport information is verified functionalClass: type: string description: >- Road functional class according to HERE Maps: - 0: Unknown - 1: Functional Class 1 - 2: Functional Class 2 - 3: Functional Class 3 - 4: Functional Class 4 - 5: Functional Class 5 controlledAccess: type: string description: >- Indicates if the road has controlled access limitedAccessRoad: type: string description: Indicates if it's a limited access road travelDirection: type: string description: Direction of travel isBoatFerry: type: string description: Indicates if it's a boat ferry route isRailFerry: type: string description: Indicates if it's a rail ferry route isMultiDigitized: type: string description: Indicates if the road is multi-digitized isDivided: type: string description: Indicates if the road is divided isDividerLegal: type: string description: Indicates if the divider is legal isFrontage: type: string description: Indicates if it's a frontage road isPaved: type: string description: Indicates if the road is paved isRamp: type: string description: Indicates if it's a ramp isPrivate: type: string description: Indicates if it's a private road hasPoiAccess: type: string description: Indicates if there's POI access intersectionCategory: type: string description: >- Type of intersection according to HERE Maps: - 0: Unknown - 1: Intersection Internal - 2: Manoeuvre - 3: Indescribable - 4: Roundabout - 5: Undefined Traffic Area - 6: Special Traffic Figure speedCategory: type: string description: |- Speed category according to HERE Maps: - 0: Unknown - 1: Over 130 km/h (80 mph) - 2: 101-130 km/h (65-80 mph) - 3: 91-100 km/h (55-64 mph) - 4: 71-90 km/h (41-54 mph) - 5: 51-70 km/h (31-40 mph) - 6: 31-50 km/h (21-30 mph) - 7: 11-30 km/h (6-20 mph) - 8: Under 11 km/h (6 mph) laneCategory: type: string description: |- Lane category according to HERE Maps: - 0: Unknown - 1: One lane - 2: Two or three lanes - 3: Four or more lanes coverageIndicator: type: string description: Coverage indicator lowMobility: type: string description: |- Low mobility indicator: - 0: Unknown (Default) - 1: Low mobility driving condition - 2: Not low mobility driving condition hasPublicAccess: type: string description: Indicates if there's public access routeTypes: type: string description: Types of routes weather: type: object description: Weather conditions at the time of the event properties: latitude: type: number description: Latitude of weather measurement location longitude: type: number description: >- Longitude of weather measurement location temperature: type: number description: Air temperature in Celsius dewPoint: type: number description: Dew point temperature in Celsius humidity: type: number description: Relative humidity percentage pressure: type: number description: Air pressure windSpeed: type: number description: Wind velocity in meters per second windDirection: type: number description: Wind direction in degrees locationId: type: string description: HERE weather location identifier precipitationType: type: string description: Precipitation type intensityOfPrecipitation: type: number description: >- Intensity of precipitation (measured in cm/h) visibility: type: number description: Visibility (measured in km) metadata: title: EntityMetadata type: object description: Internal metadata about the record. required: - addedAt - modifiedAt properties: addedAt: title: AddedAt type: string format: date-time description: >- The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider's system. modifiedAt: title: ModifiedAt type: string format: date-time description: >- The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system. raw: title: RawDataList type: array example: [] items: title: RawData type: object properties: provider: type: string schema: type: string extractedAt: type: string data: type: object required: - provider - schema - extractedAt - data required: - id - sourceId - provider - type - vehicle - startedAt - metadata x-description: >- A normalized record of a safety-related incident that occurred during a vehicle's operation. These events are detected and recorded by the telematics provider's system. next: title: Pagination Cursor type: string example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw description: Cursor used for pagination. format: cursor required: - results '400': description: Bad Request content: application/json: schema: type: object properties: code: enum: - bad_request message: type: string example: Invalid request body detail: type: array items: title: ErrorPathDetail type: object properties: message: type: string example: '''vehicleId'' property must be a valid ulid' path: type: string example: '{requestQuery}.vehicleId' suggestion: type: string example: >- Please ensure you submit a valid 'vehicleId' property context: type: object required: - message - path required: - code - message '401': description: Unauthorized content: application/json: schema: type: object properties: code: enum: - unauthorized message: type: string example: Unauthorized Request detail: type: string example: Please ensure you have a valid API key required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: code: enum: - forbidden message: type: string example: Forbidden Request detail: type: string example: >- Please ensure the connection token matches the resource you are attempting to access. required: - code - message '429': description: Too Many Requests content: application/json: schema: type: object additionalProperties: true properties: code: enum: - too_many_requests retryAfter: description: The number of seconds to wait before retrying the request type: integer example: 60 message: type: string example: Too Many Requests detail: type: string example: You have exceeded your rate limit. Please try again later. required: - code - message '500': description: Internal Server Error content: application/json: schema: type: object properties: code: enum: - internal_server_error message: type: string example: Internal Server Error detail: type: string example: Something went wrong required: - code - message '504': description: Gateway Timeout Error content: application/json: schema: type: object properties: code: enum: - gateway_timeout message: type: string example: Gateway Timeout required: - code - message components: securitySchemes: Authorization: type: http scheme: bearer ````