---
title: "Create a media retrieval request"
method: POST
path: "/cameras/media/retrieval"
tags: ["Media"]
---

# Create a media retrieval request

`POST /cameras/media/retrieval`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/cameras/media/retrieval`
- Auth: HTTP bearer

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.

## Request body

- MediaRetrievalPostMediaRetrievalRequestBody
  - `cameraRoles` string[]: 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.
  - `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).
  - `inputs` string[]: 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`
  - `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).
  - `vehicleId` string, required: Vehicle ID for which to initiate media capture. Examples: 1234

## Response `200`

OK response.

- MediaRetrievalPostMediaRetrievalResponseBody
  - `data` PostMediaRetrievalObjectResponseBody, required
    - `quotaStatus` string, required: Quota status for this media capture request. Reflects completed retrievals only; retrievals still uploading, including this request, are not yet counted and may push usage higher once they complete. Examples: Current monthly usage is 80000.4 seconds of high-res video out of 900000.0 available.
    - `retrievalId` string, required: Retrieval ID associated with this media capture request. Examples: 2308cec4-82e0-46f1-8b3c-a3592e5cc21e

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)