SAsamsara
Media

Create a media retrieval request

This endpoint creates an asynchronous request to upload certain media from a device. The closest available media to the requested timestamp is returned. Images, videos(both high resolution and low resolution) and hyperlapses are supported.Currently, only unblurred media is supported. If a device is offline, the requested media will be uploaded once it comes back online. Quota limits are enforced for media retrievals made through the API. The Create a media retrieval request response includes information about the media retrieval quota remaining for the organization. The media retrieval quota for the organization is reset at the beginning of each month.The quota is expressed using seconds of High Resolution video. 10 still images are equivalent to a 1 second of High Resolution footage.

<b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select Write Media Retrieval 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>

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.

post/cameras/media/retrieval

Request

  • Base URL
    https://api.samsara.com
  • Auth
    HTTP bearer

Request body

cameraRolesstring[]

Optional list of camera roles to resolve to analog inputs at request time. Requires an AHD4 auxcam device. Can be used alone or combined with inputs.

endTimestring required

An end time in RFC 3339 format. If endTime is the same as startTime, an image will be captured at startTime. Must be 1 second or more after startTime and no more than the maximum allowed duration per video retrieval type. Please refer to our KB articles for more information. (Examples: 2019-06-13T19:08:55Z, 2019-06-13T19:08:55.455Z, OR 2015-09-15T14:00:42-04:00).

inputsstring[]

A list of desired camera inputs for which to capture media. Only media with valid inputs (e.g. device has that input stream and device was recording at the time) will be uploaded. At least one of inputs or cameraRoles must be provided.

mediaType'image' | 'videoHighRes' | 'videoLowRes' | 'hyperlapse' required

The desired media type. If a video is requested, endTime must be after startTime. If an image is requested, endTime must be the same as startTime. Must be one of: image, videoHighRes, videoLowRes. Examples: image, videoHighRes, videoLowRes, hyperlapse. Valid values: image, videoHighRes, videoLowRes, hyperlapse

startTimestring required

A start 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).

vehicleIdstring required

Vehicle ID for which to initiate media capture. Examples: 1234

Example request

{
  "cameraRoles": [
    "front",
    "front",
    "front",
    "front"
  ],
  "endTime": "2019-06-13T19:08:55Z",
  "inputs": [
    "dashcamRoadFacing",
    "dashcamRoadFacing"
  ],
  "mediaType": "videoHighRes",
  "startTime": "2019-06-13T19:08:25Z",
  "vehicleId": "1234"
}

Response

OK response.

Example response

{
  "data": {
    "quotaStatus": "Current monthly usage is 80000.4 seconds of high-res video out of 900000.0 available.",
    "retrievalId": "2308cec4-82e0-46f1-8b3c-a3592e5cc21e"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.