Samsara Intervals API
The Intervals API from Samsara — 1 operation(s) for intervals.
OpenAPI Specification
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