Samsara Sessions API
The Sessions API from Samsara — 1 operation(s) for sessions.
OpenAPI Specification
openapi: 3.0.1
info:
description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
title: Samsara Sessions API
version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Sessions
paths:
/coaching/sessions/stream:
get:
description: "This endpoint will return coaching sessions for your organization based on the time parameters passed in. Results are paginated by sessions. If you include an endTime, the endpoint will return data up until that point. If you dont include an endTime, you can continue to poll the API real-time with the pagination cursor that gets returned on every call.\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 Coaching** under the Coaching 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: getCoachingSessions
parameters:
- description: Optional string of comma separated driver IDs. If driver ID is present, sessions for the specified driver(s) will be returned.
explode: false
in: query
name: driverIds
schema:
items:
type: string
type: array
style: form
- description: Optional string of comma separated user IDs. If coach ID is present, sessions for the specified coach(s) will be returned for either assignedCoach or completedCoach. If both driverId(s) and coachId(s) are present, sessions with specified driver(s) and coach(es) will be returned.
explode: false
in: query
name: coachIds
schema:
items:
type: string
type: array
style: form
- description: 'Optional string of comma separated statuses. Valid values: upcoming, completed, deleted.'
explode: false
in: query
name: sessionStatuses
schema:
items:
type: string
type: array
style: form
- description: Optional boolean to control whether behaviors will include coachableEvents in the response. Defaults to false.
in: query
name: includeCoachableEvents
schema:
type: boolean
- description: Required RFC 3339 timestamp that indicates when to begin receiving data. Value is compared against `updatedAtTime`
in: query
name: startTime
required: true
schema:
format: date-time
type: string
- description: Optional RFC 3339 timestamp. If not provided then the endpoint behaves as an unending feed of changes. If endTime is set the same as startTime, the most recent data point before that time will be returned per asset. Value is compared against `updatedAtTime`
in: query
name: endTime
schema:
format: date-time
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: Optional boolean indicating whether to return external IDs on supported entities
in: query
name: includeExternalIds
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsResponseBody'
description: OK response.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsUnauthorizedErrorResponseBody'
description: Unauthorized response.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsNotFoundErrorResponseBody'
description: Not Found response.
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsMethodNotAllowedErrorResponseBody'
description: Method Not Allowed response.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsTooManyRequestsErrorResponseBody'
description: Too Many Requests response.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsInternalServerErrorResponseBody'
description: Internal Server Error response.
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsNotImplementedErrorResponseBody'
description: Not Implemented response.
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsBadGatewayErrorResponseBody'
description: Bad Gateway response.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsServiceUnavailableErrorResponseBody'
description: Service Unavailable response.
'504':
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsGatewayTimeoutErrorResponseBody'
description: Gateway Timeout response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/CoachingSessionsGetCoachingSessionsBadRequestErrorResponseBody'
description: Bad Request response.
summary: Get Coaching Sessions.
tags:
- Sessions
components:
schemas:
CoachingSessionsGetCoachingSessionsBadGatewayErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsNotFoundErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsInternalServerErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsResponseBody:
properties:
data:
description: List of coaching sessions objects.
items:
$ref: '#/components/schemas/CoachingSessionsResponseResponseBody'
type: array
pagination:
$ref: '#/components/schemas/GoaPaginationResponseResponseBody'
required:
- data
- pagination
type: object
coachableEventResponseBody:
description: Object reference for the coachable event within the behavior.
properties:
id:
description: Unique ID for an event within the item in a coaching session.
example: f5271458-21f9-4a9f-a290-780c6d8840ff
type: string
required:
- id
type: object
DriverWithExternalIdObjectResponseBody:
description: A driver object with an id and map of external ids.
properties:
driverId:
description: Samsara ID of the driver.
example: 0987
type: string
externalIds:
additionalProperties:
type: string
description: A map of external ids
type: object
required:
- driverId
type: object
CoachingSessionsGetCoachingSessionsBadRequestErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsNotImplementedErrorResponseBody:
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
behaviorResponseBody:
description: Object reference for the behavior within the session.
properties:
coachableBehaviorType:
description: 'Coachable behavior type for the behavior in the coaching session. Valid values: `acceleration`, `braking`, `cameraObstruction`, `crash`, `defensiveDriving`, `didNotYield`, `drinkPolicy`, `drowsy`, `eatingDrinking`, `event`, `falsePositive`, `foodPolicy`, `forwardCollisionWarning`, `genericDistraction`, `harshTurn`, `laneDeparture`, `lateResponse`, `maskPolicy`, `maxSpeed`, `mobileUsage`, `nearCollison`, `noSeatbelt`, `obstructedCamera`, `outwardObstruction`, `passengerPolicy`, `ranRedLight`, `rollingRailroadCrossing`, `rollingStop`, `rollingStop`, `rollover`, `rolloverProtection`, `rolloverProtectionBrakeControlActivated`, `rolloverProtectionEngineControlActivated`, `severeSpeeding`, `smoking`, `speeding`, `tailgating`, `unknown`, `yawControl`, `yawControlBrakeControlActivated`, `yawControlEngineControlActivated`'
enum:
- acceleration
- braking
- cameraObstruction
- crash
- defensiveDriving
- didNotYield
- drinkPolicy
- drowsy
- eatingDrinking
- event
- falsePositive
- foodPolicy
- forwardCollisionWarning
- genericDistraction
- harshTurn
- laneDeparture
- lateResponse
- maskPolicy
- maxSpeed
- mobileUsage
- nearCollison
- noSeatbelt
- obstructedCamera
- outwardObstruction
- passengerPolicy
- ranRedLight
- rollingRailroadCrossing
- rollingStop
- rollingStop
- rollover
- rolloverProtection
- rolloverProtectionBrakeControlActivated
- rolloverProtectionEngineControlActivated
- severeSpeeding
- smoking
- speeding
- tailgating
- unknown
- yawControl
- yawControlBrakeControlActivated
- yawControlEngineControlActivated
example: forwardCollisionWarning
type: string
coachableEvents:
description: Object references for the coachableEvents within the behavior. For non Speeding events, corresponds to the unique Samsara ID of the safety event as vehicleId - eventMS, for Speeding events corresponds to the unique UUID of the event. Returned when includeCoachableEvents is 'true'. Capped at 100 coachable events per Coaching session. For sessions where coachable events exceed 100, please visit the Samsara dashboard to address this coaching session.
items:
$ref: '#/components/schemas/coachableEventResponseBody'
type: array
id:
description: Unique ID for the coaching behavior.
example: f5271458-21f9-4a9f-a290-780c6d8840ff
type: string
lastCoachedTime:
description: Time of last coached date for the same behavior label.
example: '2019-06-13T19:08:25Z'
format: date-time
type: string
note:
description: Associated note for the coaching behavior. Returned when present.
example: Need to wear seatbelt even for short trips.
type: string
updatedAtTime:
description: Time of coaching behavior update in UTC.
example: '2019-06-13T19:08:25Z'
format: date-time
type: string
required:
- coachableBehaviorType
- id
- lastCoachedTime
- updatedAtTime
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
CoachingSessionsGetCoachingSessionsServiceUnavailableErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsMethodNotAllowedErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsUnauthorizedErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsGatewayTimeoutErrorResponseBody:
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
CoachingSessionsGetCoachingSessionsTooManyRequestsErrorResponseBody:
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
CoachingSessionsResponseResponseBody:
description: List of coaching sessions objects.
properties:
assignedCoachId:
description: Unique user ID for a coaching session. Returned when a coaching session status is incomplete.
example: '45646'
type: string
behaviors:
description: Object references for the behaviors within the session.
items:
$ref: '#/components/schemas/behaviorResponseBody'
type: array
coachingType:
description: 'Coaching type for the coaching session. Valid values: `fullySharedWithManager`, `selfCoaching`, `unknown`, `unshared`, `withManager`'
enum:
- fullySharedWithManager
- selfCoaching
- unknown
- unshared
- withManager
example: unshared
type: string
completedAtTime:
description: Time coaching session is completed in UTC. Returned when a coaching session status is completed.
example: '2019-06-13T19:08:25Z'
format: date-time
type: string
completedCoachId:
description: Unique user ID for a completed coaching session. Returned when a coaching session status is completed.
example: '45646'
type: string
driver:
$ref: '#/components/schemas/DriverWithExternalIdObjectResponseBody'
dueAtTime:
description: Time coaching session is due in UTC.
example: '2019-06-13T19:08:25Z'
format: date-time
type: string
id:
description: Unique ID for the coaching session.
example: f5271458-21f9-4a9f-a290-780c6d8840ff
type: string
sessionNote:
description: Associated note for the coaching session. Returned when present.
example: Need to wear seatbelt even for short trips.
type: string
sessionStatus:
description: 'Status for the coaching session. Valid values: `unknown`, `upcoming`, `completed`, `deleted`'
enum:
- unknown
- upcoming
- completed
- deleted
example: completed
type: string
updatedAtTime:
description: Time coaching session was updated in UTC.
example: '2019-06-13T19:08:25Z'
format: date-time
type: string
required:
- behaviors
- coachingType
- driver
- dueAtTime
- id
- sessionStatus
- updatedAtTime
type: object
securitySchemes:
AccessTokenHeader:
type: http
scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
explorer-enabled: true
proxy-enabled: true