Create a snapshot
Updated at：2025-10-20
This API allows the creation of snapshots from specified disks, supporting both system disks and CDS data disks.
- To successfully create a snapshot of a system disk, the instance must be in either the Running or Stopped state.
- To successfully create a snapshot for a cloud disk server (CDS), the disk must be in the InUse (in use) or Available (pending attachment) state.
- Each cloud disk server can have up to 1,536 snapshots at the same time, including 512 manual snapshots and 1,024 automatic snapshots.
Request structure
Plain Text
1POST /v{version}/snapshot?clientToken={clientToken} HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: authorization string
4
5{
6 "volumeId":volumeId,
7 "snapshotName": snapshotName,
8 "tags": [
9 {
10 "tagKey": "tagKey",
11 "tagValue": "tagValue"
12 }
13 ]
14 "desc" : create snapshot,
15 "retentionInDays": retentionInDays
16}Request headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Whether required | Parameter location | Description |
|---|---|---|---|---|
| version | String | Yes | URL parameter | API version number |
| clientToken | String | Yes | Query | Idempotency Token, which is an ASCII string with a length not exceeding 64 bits, see details in [ClientToken Idempotency](BCC/API Reference/General Description.md#Idempotence). |
| volumeId | String | Yes | Request Body parameters | Disk ID used for snapshot creation; for system disks, use the instance ID |
| snapshotName | String | Yes | Request Body parameters | The snapshot name supports uppercase and lowercase letters, numbers, Chinese characters, and -_/special characters. It must start with a letter and be 1-65 characters long. |
| desc | String | No | Request Body parameters | Snapshot description information (optional) |
| tags | List<[TagModel](BCC/API Reference/Appendix.md#TagModel)> | No | Request Body parameters | Tag binding |
| retentionInDays | int | No | Request Body parameters | Retention period of the snapshot, defaulting to -1 for permanent retention, ranging from 1 to 10,000 days |
Response headers
No special headers are required beyond the standard ones.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| snapshotId | String | ID of the created snapshot |
Error codes
| Error code | Error description | HTTP status code | Chinese explanation |
|---|---|---|---|
| BadRequest | Bad request parameters or illegal request. | 400 | Invalid request parameters |
| Snapshot.SnapshotNameInvalid | snapshot name is invalid. | 400 | Invalid name |
| Instance.SnapshotLimitExceeded | The number of snapshot will exceed the quota limit. | 413 | Snapshot quota exceeded |
Request example
Plain Text
1POST /v2/snapshot?clientToken=be31b98c-5e41-4838-9830-9be700de5a20 HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
4
5{
6 "volumeId": "v-nky7qeom",
7 "snapshotName": "example-001"
8}Response example
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
3Date: Wed, 03 Dec 2014 06:42:19 GMT
4Content-Type: application/json;charset=UTF-8
5Server: BWS
6
7{
8 "snapshotId" : "s-6r3dam6F"
9}