Samsara Events API

openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Events API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Events
paths:
  /beta/fleet/hos/drivers/eld-events:
    get:
      description: "Get all HOS ELD events in a time range, grouped by driver. Attributes will be populated depending on which ELD Event Type is being returned.\n\n <b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Read ELD Compliance Settings (US)** under the Compliance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
      operationId: getHosEldEvents
      parameters:
      - description: ' A start time in RFC 3339 format. Defaults to now if not provided. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: startTime
        required: true
        schema:
          type: string
      - description: ' An end time in RFC 3339 format. Defaults to now if not provided. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: endTime
        required: true
        schema:
          type: string
      - description: ' A filter on the data based on this comma-separated list of driver IDs and externalIds. Example: `driverIds=1234,5678,payroll:4841`'
        explode: false
        in: query
        name: driverIds
        schema:
          items:
            type: string
          type: array
        style: form
      - description: ' A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`'
        in: query
        name: tagIds
        schema:
          type: string
      - description: ' A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`'
        in: query
        name: parentTagIds
        schema:
          type: string
      - description: 'If value is `deactivated`, only drivers that are deactivated will appear in the response. This parameter will default to `active` if not provided (fetching only active drivers).  Valid values: `active`, `deactivated`'
        in: query
        name: driverActivationStatus
        schema:
          default: active
          enum:
          - active
          - deactivated
          type: string
      - description: ' If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.'
        in: query
        name: after
        schema:
          type: string
      - description: The limit for how many objects will be in the response. Default and max for this value is 25 objects.
        in: query
        name: limit
        schema:
          default: 25
          maximum: 25
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsResponseBody'
          description: OK response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsUnauthorizedErrorResponseBody'
          description: Unauthorized response.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsNotFoundErrorResponseBody'
          description: Not Found response.
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsMethodNotAllowedErrorResponseBody'
          description: Method Not Allowed response.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsTooManyRequestsErrorResponseBody'
          description: Too Many Requests response.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsInternalServerErrorResponseBody'
          description: Internal Server Error response.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsNotImplementedErrorResponseBody'
          description: Not Implemented response.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsBadGatewayErrorResponseBody'
          description: Bad Gateway response.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsServiceUnavailableErrorResponseBody'
          description: Service Unavailable response.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsGatewayTimeoutErrorResponseBody'
          description: Gateway Timeout response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HosEldEventsGetHosEldEventsBadRequestErrorResponseBody'
          description: Bad Request response.
      summary: '[beta] Get Driver HOS ELD Events'
      tags:
      - Events
  /v1/fleet/vehicles/{vehicleId}/safety/harsh_event:
    get:
      description: "<n class=\"warning\">\n<nh>\n<i class=\"fa fa-exclamation-circle\"></i>\nThis endpoint is still on our legacy API.\n</nh>\n</n>\n\nFetch harsh event details for a vehicle. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read Safety Events & Scores** under the Safety & Cameras category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: V1getVehicleHarshEvent
      parameters:
      - description: ID of the vehicle. Must contain only digits 0-9.
        in: path
        name: vehicleId
        required: true
        schema:
          format: int64
          type: integer
      - description: Timestamp in milliseconds representing the timestamp of a harsh event.
        in: query
        name: timestamp
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1VehicleHarshEventResponse'
          description: Harsh event details.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Unexpected error.
      summary: Fetch Harsh Events
      tags:
      - Events
components:
  schemas:
    HosEldEventsGetHosEldEventsBadGatewayErrorResponseBody:
      description: Bad Gateway
      properties:
        message:
          description: Message of error
          example: 'rpc error: code = Unknown desc = connection refused'
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    HosEldEventsGetHosEldEventsServiceUnavailableErrorResponseBody:
      description: Service unavailable
      properties:
        message:
          description: Message of error
          example: context deadline exceeded
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    HosEldEventRemarkObjectResponseBody:
      properties:
        comment:
          description: The content of the remark.
          example: Pre-Trip Inspection
          type: string
        locationDescription:
          description: The location description entered by the user
          example: Near San Francisco
          type: string
        time:
          description: The time in RFC 3339 format at which the remark was created.
          example: '2019-06-13T19:08:25Z'
          type: string
      required:
      - comment
      - locationDescription
      - time
      type: object
    V1ErrorResponse:
      description: Error message describing why the request failed.
      type: string
    HosEldEventsGetHosEldEventsNotImplementedErrorResponseBody:
      description: Requested endpoint is not yet implemented
      properties:
        message:
          description: Message of error
          example: Not implemented.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    V1VehicleHarshEventResponse_location:
      properties:
        address:
          description: Address of location where the harsh event occurred
          example: 350 Rhode Island St, San Francisco, CA
          type: string
        latitude:
          description: Latitude of location where the harsh event occurred
          example: 33.07614328
          type: number
        longitude:
          description: Longitude of location where the harsh event occurred
          example: -96.14907287
          type: number
      type: object
    HosEldEventObjectResponseBody:
      description: An event that refers to a discrete instance in time with various data elements. Depending on the type of event, not every field will be populated. For more information, see the ELD Mandate [section 3.1.2](https://www.ecfr.gov/cgi-bin/retrieveECFR?gp=1&ty=HTML&h=L&mc=true&=PART&n=pt49.5.395#ap49.5.395_138.a).
      properties:
        accumulatedVehicleMeters:
          description: The accumulated meters in the given ignition power on cycle.
          example: 106
          format: int64
          type: integer
        elapsedEngineHours:
          description: The elapsed time in the engine's operation in the given ignition power on cycle.
          example: 284.1
          format: double
          type: number
        eldEventCode:
          description: 'A dependent attribute on `eldEventType` that specifies the nature of the event, as defined in the ELD Mandate [section 7.20](https://www.ecfr.gov/cgi-bin/retrieveECFR?gp=1&ty=HTML&h=L&mc=true&=PART&n=pt49.5.395#ap49.5.395_138.a).  Valid values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`'
          example: 3
          maximum: 9
          minimum: 1
          type: integer
        eldEventRecordOrigin:
          description: 'An attribute for the event record indicating whether it is automatically recorded, or edited, entered or accepted by the driver, requested by another authenticated user, or assumed from unidentified driver profile, as defined in the ELD Mandate [section 7.22](https://www.ecfr.gov/cgi-bin/retrieveECFR?gp=1&ty=HTML&h=L&mc=true&=PART&n=pt49.5.395#ap49.5.395_138.a).  Valid values: `1`, `2`, `3`, `4`'
          example: 2
          maximum: 4
          minimum: 1
          type: integer
        eldEventRecordStatus:
          description: 'An attribute for the event record indicating whether an event is active or inactive and further, if inactive, whether it is due to a change or lack of confirmation by the driver or due to a driver''s rejection of change request, as defined in the ELD Mandate [section 7.23](https://www.ecfr.gov/cgi-bin/retrieveECFR?gp=1&ty=HTML&h=L&mc=true&=PART&n=pt49.5.395#ap49.5.395_138.a).  Valid values: `1`, `2`, `3`, `4`'
          example: 2
          maximum: 4
          minimum: 1
          type: integer
        eldEventType:
          description: 'An attribute specifying the type of ELD event, as defined in the ELD Mandate [section 7.25](https://www.ecfr.gov/cgi-bin/retrieveECFR?gp=1&ty=HTML&h=L&mc=true&=PART&n=pt49.5.395#ap49.5.395_138.a).  Valid values: `1`, `2`, `3`, `4`, `5`, `6`, `7`'
          example: 6
          maximum: 7
          minimum: 1
          type: integer
        location:
          $ref: '#/components/schemas/HosEldEventLocationObjectResponseBody'
        malfunctionDiagnosticCode:
          description: 'A code that further specifies the underlying malfunction or data diagnostic event, as defined in the ELD Mandate [section 7.34](https://www.ecfr.gov/cgi-bin/retrieveECFR?gp=1&ty=HTML&h=L&mc=true&=PART&n=pt49.5.395#ap49.5.395_138.a).  Valid values: `P`, `E`, `T`, `L`, `R`, `S`, `O`, `1`, `2`, `3`, `4`, `5`, `6`'
          enum:
          - P
          - E
          - T
          - L
          - R
          - S
          - O
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          - '6'
          example: P
          type: string
        remark:
          $ref: '#/components/schemas/HosEldEventRemarkObjectResponseBody'
        time:
          description: 'A time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
          example: '2019-06-13T19:08:25Z'
          type: string
        totalEngineHours:
          description: The aggregated time of a vehicle's engine's operation since its inception.
          example: 2894.1
          format: double
          type: number
        totalVehicleMeters:
          description: The total meters recorded for the vehicle.
          example: 1004566
          format: int64
          type: integer
        vehicle:
          $ref: '#/components/schemas/GoaVehicleTinyResponseResponseBody'
      required:
      - eldEventCode
      - eldEventType
      - time
      type: object
    HosEldEventsGetHosEldEventsNotFoundErrorResponseBody:
      description: Resource not found
      properties:
        message:
          description: Message of error
          example: Object not found.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    GoaPaginationResponseResponseBody:
      description: Pagination parameters.
      properties:
        endCursor:
          description: 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.
          example: MjkY
          type: string
        hasNextPage:
          description: True if there are more pages of results immediately available after this endCursor.
          example: true
          type: boolean
      required:
      - endCursor
      - hasNextPage
      type: object
    HosEldEventLocationObjectResponseBody:
      properties:
        city:
          description: The best effort city for the latitude and longitude.
          example: San Francisco
          type: string
        eldLocation:
          description: Relative location to the city, village, or town with population of 5,000 or greater.
          example: 3.1 mi WSW San Francisco, CA
          type: string
        latitude:
          description: The latitude of the location.
          example: 123.456
          format: double
          type: number
        longitude:
          description: The longitude of the location.
          example: 37.459
          format: double
          type: number
        state:
          description: The best effort state for the latitude and longitude.
          example: CA
          type: string
      type: object
    HosEldEventsGetHosEldEventsInternalServerErrorResponseBody:
      description: An internal server error occurred
      properties:
        message:
          description: Message of error
          example: Failed to execute GraphQL query.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    GoaVehicleTinyResponseResponseBody:
      description: A minified vehicle object. This object is only returned if the route is assigned to the vehicle.
      properties:
        externalIds:
          additionalProperties:
            type: string
          description: A map of external ids
          type: object
        id:
          description: ID of the vehicle
          example: '494123'
          type: string
        name:
          description: Name of the vehicle
          example: 'Fleet Truck #1'
          type: string
      type: object
    V1VehicleHarshEventResponse:
      description: Harsh event details for a vehicle
      properties:
        downloadForwardVideoUrl:
          description: URL for downloading the forward facing video
          example: https://samsara-dashcam-videos.s3.us-west-2.amazonaws.com/123/212123456789012/1539201872984/abC123De4-camera-video-segment-123456789.mp4?...
          type: string
        downloadInwardVideoUrl:
          description: URL for downloading the inward facing video
          example: https://samsara-dashcam-videos.s3.us-west-2.amazonaws.com/123/212123456789012/1539201872984/abC123De4-camera-video-segment-driver-123456789.mp4?...
          type: string
        downloadTrackedInwardVideoUrl:
          description: URL for downloading the tracked inward facing video
          example: https://samsara-dashcam-videos.s3.us-west-2.amazonaws.com/123/212123456789012/1539201872984/abC123De4-camera-video-segment-driver-123456789.tracked.mp4?...
          type: string
        harshEventType:
          description: 'Type of the harsh event. One of: [Crash, Harsh Acceleration, Harsh Braking, Harsh Turn, ROP Engine, ROP Brake, YC Engine, YC Brake, Harsh Event]'
          example: Harsh Braking
          type: string
        incidentReportUrl:
          description: URL of the associated incident report page
          example: https://cloud.samsara.com/o/1234/fleet/reports/safety/vehicle/212123456789012/incident/1539201882984
          type: string
        isDistracted:
          description: Whether the driver was deemed distracted during this harsh event
          example: true
          type: boolean
        location:
          $ref: '#/components/schemas/V1VehicleHarshEventResponse_location'
      required:
      - harshEventType
      - incidentReportUrl
      type: object
    HosEldEventsGetHosEldEventsGatewayTimeoutErrorResponseBody:
      description: Gateway timeout
      properties:
        message:
          description: Message of error
          example: context deadline exceeded
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    HosEldEventsGetHosEldEventsResponseBody:
      properties:
        data:
          description: List of drivers and their ELD event objects data.
          items:
            $ref: '#/components/schemas/HosDriversEldEventObjectResponseBody'
          type: array
        pagination:
          $ref: '#/components/schemas/GoaPaginationResponseResponseBody'
      required:
      - data
      type: object
    HosDriversEldEventObjectResponseBody:
      properties:
        driverActivationStatus:
          description: 'A value indicating whether the driver is active or deactivated.  Valid values: `active`, `deactivated`'
          enum:
          - active
          - deactivated
          example: active
          type: string
        eldEvents:
          description: List of ELD event objects.
          items:
            $ref: '#/components/schemas/HosEldEventObjectResponseBody'
          type: array
        externalIds:
          additionalProperties:
            type: string
          description: A map of external ids
          type: object
        id:
          description: ID of the driver.
          example: '494123'
          type: string
        name:
          description: Name of the driver.
          example: Joe Driver
          type: string
      required:
      - driverActivationStatus
      - eldEvents
      - id
      - name
      type: object
    HosEldEventsGetHosEldEventsUnauthorizedErrorResponseBody:
      description: Unauthorized
      properties:
        message:
          description: Message of error
          example: Invalid token.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    HosEldEventsGetHosEldEventsTooManyRequestsErrorResponseBody:
      description: Too many requests
      properties:
        message:
          description: Message of error
          example: Exceeded rate limit.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    HosEldEventsGetHosEldEventsMethodNotAllowedErrorResponseBody:
      description: Method not allowed
      properties:
        message:
          description: Message of error
          example: DELETE not allowed on /endpoint.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    HosEldEventsGetHosEldEventsBadRequestErrorResponseBody:
      description: Bad Request parameters
      properties:
        message:
          description: Message of error
          example: Invalid value for parameter.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true