openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Intervals API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Intervals
paths:
  /speeding-intervals/stream:
    get:
      description: "This endpoint will return all speeding intervals associated with trips that have been collected for your organization based on the time parameters passed in. Only completed trips are included. Results are paginated.\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 Speeding Intervals** under the Speeding Intervals 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: getSpeedingIntervals
      parameters:
      - description: Comma-separated list of asset IDs. Include up to 50 asset IDs.
        explode: false
        in: query
        name: assetIds
        required: true
        schema:
          items:
            type: string
          type: array
        style: form
      - description: RFC 3339 timestamp that indicates when to begin receiving data. Value is compared against `updatedAtTime` or `tripStartTime` depending on the queryBy parameter.
        in: query
        name: startTime
        required: true
        schema:
          type: string
      - description: RFC 3339 timestamp which is compared against `updatedAtTime` or `tripStartTime` depending on the queryBy parameter. If not provided then the endpoint behaves as an unending feed of changes.
        in: query
        name: endTime
        schema:
          type: string
      - description: 'Decide which timestamp the `startTime` and `endTime` are compared to.  Valid values: `updatedAtTime`, `tripStartTime`'
        in: query
        name: queryBy
        schema:
          default: updatedAtTime
          enum:
          - updatedAtTime
          - tripStartTime
          type: string
      - description: Indicates whether or not to return expanded asset data
        in: query
        name: includeAsset
        schema:
          default: false
          type: boolean
      - description: Indicates whether or not to return trip's driver id
        in: query
        name: includeDriverId
        schema:
          default: false
          type: boolean
      - 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: 'Optional string of comma-separated severity levels to filter speeding intervals by. Valid values:  light, moderate, heavy, severe.'
        explode: false
        in: query
        name: severityLevels
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsResponseBody'
          description: OK response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsUnauthorizedErrorResponseBody'
          description: Unauthorized response.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsNotFoundErrorResponseBody'
          description: Not Found response.
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsMethodNotAllowedErrorResponseBody'
          description: Method Not Allowed response.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsTooManyRequestsErrorResponseBody'
          description: Too Many Requests response.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsInternalServerErrorResponseBody'
          description: Internal Server Error response.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsNotImplementedErrorResponseBody'
          description: Not Implemented response.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsBadGatewayErrorResponseBody'
          description: Bad Gateway response.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsServiceUnavailableErrorResponseBody'
          description: Service Unavailable response.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsGatewayTimeoutErrorResponseBody'
          description: Gateway Timeout response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedingIntervalsGetSpeedingIntervalsBadRequestErrorResponseBody'
          description: Bad Request response.
      summary: '[beta] Get Speeding Intervals'
      tags:
      - Intervals
components:
  schemas:
    SpeedingIntervalsGetSpeedingIntervalsGatewayTimeoutErrorResponseBody:
      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
    SpeedingIntervalsGetSpeedingIntervalsMethodNotAllowedErrorResponseBody:
      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
    SpeedingIntervalsGetSpeedingIntervalsServiceUnavailableErrorResponseBody:
      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
    TripAssetResponseBody:
      description: Asset that the location readings are tied to
      properties:
        id:
          description: Unique ID for the asset object that is reporting the location.
          example: '12345'
          type: string
        name:
          description: Name for the asset object that is reporting the location. Only returns when `includeAsset` is set to `true`.
          example: MyAsset-1234
          type: string
        type:
          description: '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`'
          enum:
          - uncategorized
          - trailer
          - equipment
          - unpowered
          - vehicle
          example: trailer
          type: string
        vin:
          description: VIN for the asset object that is reporting the location. Only returns when `includeAsset` is set to `true`.
          example: 1GBJ6P1B2HV112765
          type: string
      required:
      - id
      type: object
    SpeedingIntervalsGetSpeedingIntervalsNotFoundErrorResponseBody:
      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
    SpeedingIntervalsGetSpeedingIntervalsResponseBody:
      properties:
        data:
          description: List of speeding intervals associated with trips.
          items:
            $ref: '#/components/schemas/TripSpeedingIntervalsResponseBody'
          type: array
        pagination:
          $ref: '#/components/schemas/GoaPaginationResponseResponseBody'
      required:
      - data
      - pagination
      type: object
    SpeedingIntervalsGetSpeedingIntervalsNotImplementedErrorResponseBody:
      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
    SpeedingIntervalsGetSpeedingIntervalsUnauthorizedErrorResponseBody:
      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
    AddressResponseResponseBody:
      description: Closest address that the GPS latitude and longitude match to.
      properties:
        city:
          description: The name of the city
          example: New York
          type: string
        country:
          description: The country
          example: USA
          type: string
        neighborhood:
          description: The name of the neighborhood if one exists
          example: Mission District
          type: string
        pointOfInterest:
          description: Point that may be of interest to the user
          example: The Eiffel Tower
          type: string
        postalCode:
          description: The zip code
          example: '10010'
          type: string
        state:
          description: The name of the state
          example: New York
          type: string
        street:
          description: The street name
          example: Main Street
          type: string
        streetNumber:
          description: Street number of the address
          example: '16'
          type: string
      type: object
    SpeedingIntervalLocationResponseResponseBody:
      description: Location object of the closest location point to the interval.
      properties:
        accuracyMeters:
          description: Radial accuracy of gps location in meters. This will only return if strong GPS is not available.
          example: 5.801
          format: double
          type: number
        address:
          $ref: '#/components/schemas/AddressResponseResponseBody'
        headingDegrees:
          description: Heading of the asset in degrees. May be 0 if the asset is not moving.
          example: 120
          format: int64
          type: integer
        latitude:
          description: Latitude of the closest location point to the interval.
          example: 37.7749
          format: double
          type: number
        longitude:
          description: Longitude of the closest location point to the interval.
          example: 137.2719
          format: double
          type: number
      required:
      - address
      - headingDegrees
      - latitude
      - longitude
      type: object
    SpeedingIntervalsGetSpeedingIntervalsBadRequestErrorResponseBody:
      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
    TripSpeedingIntervalsResponseBody:
      description: TripSpeedingIntervals
      properties:
        asset:
          $ref: '#/components/schemas/TripAssetResponseBody'
        createdAtTime:
          description: UTC time the trip was created in Samsara in RFC 3339 format.
          example: '2023-01-27T07:06:25Z'
          type: string
        driverId:
          description: The driver ID assigned to the trip. Only returned if includeDriverId is set to true. 'null' if no driver id.
          example: '12345'
          type: string
        intervals:
          description: List of speeding intervals that belong to the trip. The full list of intervals associated with the trip is always returned, empty if no intervals exist.
          items:
            $ref: '#/components/schemas/SpeedingIntervalResponseBody'
          type: array
        tripStartTime:
          description: UTC time the trip started in RFC 3339 format.
          example: '2023-01-27T07:06:25Z'
          type: string
        updatedAtTime:
          description: UTC time the trip was last updated in Samsara in RFC 3339 format. Valid updates are when trip's endTime populates or interval.isDismissed changes value.
          example: '2023-01-27T10:04:20Z'
          type: string
      required:
      - asset
      - createdAtTime
      - intervals
      - tripStartTime
      - updatedAtTime
      type: object
    SpeedingIntervalsGetSpeedingIntervalsBadGatewayErrorResponseBody:
      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
    SpeedingIntervalResponseBody:
      description: Speeding Interval Object
      properties:
        endTime:
          description: UTC time the interval ended in RFC 3339 format.
          example: '2023-01-27T07:06:25Z'
          type: string
        isDismissed:
          description: Whether the interval is dismissed.
          example: true
          type: boolean
        location:
          $ref: '#/components/schemas/SpeedingIntervalLocationResponseResponseBody'
        maxSpeedKilometersPerHour:
          description: The max speed exceeded for the speeding interval.
          example: 65
          format: double
          type: number
        postedSpeedLimitKilometersPerHour:
          description: The posted speed limit associated with the speeding interval.
          example: 75
          format: double
          type: number
        severityLevel:
          description: 'Specifies the severity level of the speeding interval.  Valid values: `light`, `moderate`, `heavy`, `severe`'
          enum:
          - light
          - moderate
          - heavy
          - severe
          example: severe
          type: string
        startTime:
          description: UTC time the interval started in RFC 3339 format.
          example: '2023-01-27T07:06:25Z'
          type: string
      required:
      - endTime
      - isDismissed
      - location
      - maxSpeedKilometersPerHour
      - postedSpeedLimitKilometersPerHour
      - severityLevel
      - startTime
      type: object
    SpeedingIntervalsGetSpeedingIntervalsInternalServerErrorResponseBody:
      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
    SpeedingIntervalsGetSpeedingIntervalsTooManyRequestsErrorResponseBody:
      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
    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
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true