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.

Rate limit: 100 requests/min (learn more about rate limits here).

To use this endpoint, select Write Media Retrieval under the Safety & Cameras 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.

POST /cameras/media/retrieval

Create a media retrieval request

cURL

curl --request POST \
  --url https://api.samsara.com/cameras/media/retrieval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endTime": "2019-06-13T19:08:55Z",
  "inputs": [
    "dashcamRoadFacing",
    "dashcamRoadFacing"
  ],
  "mediaType": "videoHighRes",
  "startTime": "2019-06-13T19:08:25Z",
  "vehicleId": "1234"
}
'

200

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

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

endTime · string · 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).

Example:

"2019-06-13T19:08:55Z"

inputs · enum<string>[] · required

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. An empty list is invalid.

input Valid values: dashcamRoadFacing, dashcamDriverFacing, analog1, analog2, analog3, analog4

Available options: dashcamRoadFacing, dashcamDriverFacing, analog1, analog2, analog3, analog4

Example:

["dashcamRoadFacing", "dashcamRoadFacing"]

mediaType · enum<string> · 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

Available options: image, videoHighRes, videoLowRes, hyperlapse

Example:

"videoHighRes"

startTime · string · 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).

Example:

"2019-06-13T19:08:25Z"

vehicleId · string · required

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

Example:

"1234"

Response

200

application/json

OK response.

data · object · required

Show child attributes