# Cloud-based screenshot upload (/en/realtime-media/cloud-recording/build/start-a-recording/screen-capture)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
You can use Cloud Recording RESTful API to take screenshots of a video stream in a channel and upload the screenshots to your third-party cloud storage.
The following two screenshot methods are supported:
* Take screenshots only.
* Capture screenshots and recording during a recording process. Agora only charges recording fees.
For pricing details, see [Pricing](/en/realtime-media/cloud-recording/reference/pricing).
To implement client-side screen capture, see [Screenshot Upload](../../../video-calling/advanced/screenshot-upload).
## Implementation [#implementation]
Note
The initial Queries Per Second (QPS) limit is 10 per app ID when you register. If you need to extend the limit for QPS, contact [support@agora.io](mailto\:support@agora.io). For more details on existing limitations, see [Integration best practices](/en/realtime-media/cloud-recording/build/best-practices/integration-best-practices#check-the-limits).
### Get a resource ID [#get-a-resource-id]
Before recording, call the [`acquire`](/en/api-reference/api-ref/cloud-recording#acquire) method to apply for a resource ID.
#### Example `acquire` request over HTTPS [#example-acquire-request-over-https]
* Request URL:
```html
https://api.agora.io/v1/apps//cloud_recording/acquire
```
* `Content-type`: `application/json;charset=utf-8`
* `Authorization`: Basic authorization. For more information, see [How to pass the basic HTTP authentication](../../reference/restful-authentication).
* Request body:
```json
{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"resourceExpiredHour": 24,
"scene": 0
}
}
```
### Start recording [#start-recording]
Set `mode` to `individual` when calling [`start`](/en/api-reference/api-ref/cloud-recording#start) to enable [individual recording mode](/en/realtime-media/cloud-recording/build/start-a-recording/individual-mode).
You cannot switch to a different recording mode once you start recording.
To capture screenshots, you need to configure the following parameters in `clientRequest`:
| Parameter | Description | Note |
| :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`token`](../../reference/glossary#token) | The dynamic key used for the channel to record. | Required if the channel uses a token |
| [`recordingConfig`](/en/api-reference/api-ref/cloud-recording#recordingconfig) | Configures stream subscription, transcoding, and the profile of the output audio and video. | Required |
| [`snapshotConfig`](/en/api-reference/api-ref/cloud-recording#snapshotconfig) | Configures the time interval between two successive screenshots and the file format of the screenshots. `snapshotConfig` includes the following fields:- `captureInterval`: (Optional) Integer. The time interval (in seconds) between two successive screenshots. captureInterval should be within the range \[1, 3600]. The default value is `10`.
- `fileType`: JSONArray. File format of the screenshots. fileType can only take \["jpg"], setting screenshots to the JPG format. | Required |
| [`storageConfig`](/en/api-reference/api-ref/cloud-recording#storageconfig) | Configures the third-party cloud storage. | Required |
| [`recordingFileConfig`](/en/api-reference/api-ref/cloud-recording#recordingfileconfig) | Configurations for the recorded files. | If you are recording and taking screenshots in a recording process, this parameter is required; if you are only taking screenshots in a recording process, you cannot fill in this parameter. |
#### Example `start` request over HTTPS [#example-start-request-over-https]
* Request URL:
```html
https://api.agora.io/v1/apps//cloud_recording/resourceid//mode/individual/start
```
* `Content-type`: `application/json;charset=utf-8`
* `Authorization`: Basic authorization. For more information, see [How to pass the basic HTTP authentication](../../reference/restful-authentication).
* Request body:
**Capture screenshots only**
```json
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "",
"recordingConfig": {
"channelType": 1,
"subscribeUidGroup": 0
},
"snapshotConfig": {
"captureInterval": 5,
"fileType": [
"jpg"
]
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": [
"directory1",
"directory2"
]
}
}
}
```
**Capture screenshots and recording**
```json
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 1,
"channelType": 0
},
"snapshotConfig": {
"captureInterval": 5,
"fileType": [
"jpg"
]
},
"recordingFileConfig": {
"avFileType": [
"hls"
]
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": [
"directory1",
"directory2"
]
}
}
}
```
## Screenshot files [#screenshot-files]
The naming convention of screenshot files is `___uid_s___uid_e_video_.jpg`, where:
* ` `is the recording ID.
* `` is the channel name.
* `` is the user ID.
* `` is the UTC time when the screenshot was generated. The time zone is UTC+0, and the timestamp consists of the year, month, day, hour, minute, second, and millisecond. For example, if `utc` is `20190611073246073`, the screenshot was generated on June 11, 2019, at 07:32:46.073 a.m.
The screenshot file format is determined by `fileType` you set in `start`. Currently only the JPG format is supported.
When [a cloud recording server is disconnected or the process killed](../../index#features), the cloud recording service enables the high availability mechanism, where the fault processing center automatically switches to a new server within 90 seconds to resume the service. When the service enables the mechanism, the screenshot filenames are prepended with `bak`, where `n` stands for the number of times the mechanism is enabled in a recording and starts off with `0`. Taking the filename `bak0_sid_channel1__uid_s_123__uid_e_video_20190611073246073.jpg` as an example, `bak0` indicates that this file was generated after the service enabled the high availability mechanism for the first time.
## Considerations [#considerations]
Pay attention to the following parameters as incorrect settings result in errors and failure to capture screenshots:
* In the URL of your request, you must set `mode` as `individual`.
* Do not set `recordingFileConfig`.
* `streamTypes` must be `1` or `2`.
* If you set `subscribeAudioUid`, you must also set `subscribeVideoUids`.
If a user stops sending video stream during a session, the Cloud Recording service stops taking screenshots until the stream resumes.