Get coaching sessions.

get https://api.samsara.com/coaching/sessions/stream

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 don’t include an endTime, you can continue to poll the API real-time with the pagination cursor that gets returned on every call.

Rate limit: 5 requests/sec (learn more about rate limits here).

To use this endpoint, select Read Coaching under the Coaching category when creating or editing an API token. Learn More.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

Query Params

driverIds

array of strings

Optional string of comma separated driver IDs. If driver ID is present, sessions for the specified driver(s) will be returned.

driverIds

coachIds

array of strings

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.

coachIds

sessionStatuses

array of strings

Optional string of comma separated statuses. Valid values: “upcoming”, “completed”, “deleted”.

sessionStatuses

includeCoachableEvents

boolean

Optional boolean to control whether behaviors will include coachableEvents in the response. Defaults to false.

startTime

date-time

required

Required RFC 3339 timestamp that indicates when to begin receiving data. Value is compared against updatedAtTime

endTime

date-time

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

after

string

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.

includeExternalIds

boolean

Optional boolean indicating whether to return external IDs on supported entities

Responses

Response body

object

data

array of objects

required

List of coaching sessions objects.

data*

object

assignedCoachId

string

Unique user ID for a coaching session. Returned when a coaching session status is “incomplete”.

behaviors

array of objects

required

Object references for the behaviors within the session.

behaviors*

object

coachableBehaviorType

string

required

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, hosViolation, idling, 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

acceleration braking cameraObstruction crash defensiveDriving didNotYield drinkPolicy drowsy eatingDrinking event falsePositive foodPolicy forwardCollisionWarning genericDistraction harshTurn hosViolation idling laneDeparture lateResponse maskPolicy maxSpeed mobileUsage nearCollison noSeatbelt obstructedCamera outwardObstruction passengerPolicy ranRedLight rollingRailroadCrossing rollingStop rollover rolloverProtection rolloverProtectionBrakeControlActivated rolloverProtectionEngineControlActivated severeSpeeding smoking speeding tailgating unknown yawControl yawControlBrakeControlActivated yawControlEngineControlActivated

coachableEvents

array of objects

Object references for the coachableEvents within the behavior. 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. Corresponds to the following unique identifiers: Non-Speeding Safety events - unique Samsara ID of the safety event as 'vehicleId - eventMS'. Speeding events - unique UUID of the event. Day of HOS Violations - unique Samsara ID of the day of violations as '{driverId},{date}'. Idling events - unique UUID of the event.

coachableEvents

object

string

required

Unique ID for an event within the item in a coaching session.

string

required

Unique ID for the coaching behavior.

lastCoachedTime

date-time

required

Time of last coached date for the same behavior label.

note

string

Associated note for the coaching behavior. Returned when present.

updatedAtTime

date-time

required

Time of coaching behavior update in UTC.

coachingType

string

required

Coaching type for the coaching session. Valid values: fullySharedWithManager, selfCoaching, unknown, unshared, withManager

fullySharedWithManager selfCoaching unknown unshared withManager

completedAtTime

date-time

Time coaching session is completed in UTC. Returned when a coaching session status is “completed”.

completedCoachId

string

Unique user ID for a completed coaching session. Returned when a coaching session status is “completed”.

driver

object

required

A driver object with an id and map of external ids.

dueAtTime

date-time

required

Time coaching session is due in UTC.

string

required

Unique ID for the coaching session.

sessionNote

string

Associated note for the coaching session. Returned when present.

sessionStatus

string

required

Status for the coaching session. Valid values: unknown, upcoming, completed, deleted

unknown upcoming completed deleted

updatedAtTime

date-time

required

Time coaching session was updated in UTC.

pagination

object

required

Pagination parameters.

endCursor

string

required

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.

hasNextPage

boolean

required

True if there are more pages of results immediately available after this endCursor.

Language

Credentials

Bearer

URL


xxxxxxxxxx
1
curl --request GET \
2
     --url https://api.samsara.com/coaching/sessions/stream \
3
     --header 'accept: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200OK response.

401Unauthorized response.

404Not Found response.

405Method Not Allowed response.

429Too Many Requests response.

500Internal Server Error response.

501Not Implemented response.

502Bad Gateway response.

503Service Unavailable response.

504Gateway Timeout response.

defaultBad Request response.