All Products
Search
Document Center

Elastic Compute Service:DescribeSnapshots

Last Updated:Mar 19, 2024

Queries all the snapshots of an Elastic Compute Service (ECS) instance or a disk.

Operation description

You can configure multiple request parameters such as InstanceId, DiskId, and SnapshotIds to query snapshots. Configured parameters have logical AND relations. Only the configured parameters are included in the filter conditions.

When you use Alibaba Cloud CLI to call an API operation, you must specify request parameter values of different data types in required formats. For more information, see Parameter format overview.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
InstanceIdstringNo

The instance ID.

i-bp67acfmxazb4p****
DiskIdstringNo

The disk ID.

d-bp67acfmxazb4p****
SnapshotLinkIdstringNo

The snapshot chain ID. You can specify a JSON array that contains up to 100 snapshot chain IDs. Separate the snapshot chain IDs with commas (,).

["sl-bp1grgphbcc9brb5****", "sl-bp1c4izumvq0i5bs****", … "sl-bp1akk7isz866dds****"]
RegionIdstringYes

The region ID of the disk. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
SnapshotIdsstringNo

The IDs of snapshots. You can specify a JSON array that consists of up to 100 snapshot IDs. Separate the snapshot IDs with commas (,).

["s-bp67acfmxazb4p****", "s-bp67acfmxazb5p****", … "s-bp67acfmxazb6p****"]
PageNumberintegerNo

The page number. Page starts from page 1.

Default value: 1.

1
PageSizeintegerNo

The number of entries per page. Valid values: 1 to 100.

Default value: 10.

10
NextTokenstringNo

The pagination token that is used in the next request to retrieve a new page of results. You must specify the token that is obtained from the previous query as the value of NextToken.

caeba0bbb2be03f84eb48b699f0a4883
MaxResultsintegerNo

The maximum number of entries per page. Valid values: 1 to 100.

Default value: 10.

10
SnapshotNamestringNo

The name of the snapshot.

testSnapshotName
StatusstringNo

The status of the snapshot. Valid values:

  • progressing: The snapshot is being created.
  • accomplished: The snapshot is created.
  • failed: The snapshot fails to be created.
  • all (default): This value indicates all snapshot states.
all
SnapshotTypestringNo

The type of the snapshot. Valid values:

  • auto: automatic snapshot
  • user: manual snapshot
  • all (default): all snapshot types
all
Filter.1.KeystringNo

The key of filter 1 that is used to query resources. Set the value to CreationStartTime. You can specify a time by configuring both Filter.1.Key and Filter.1.Value to query resources that were created after the time.

CreationStartTime
Filter.2.KeystringNo

The key of filter 2 that is used to query resources. Set the value to CreationEndTime. You can specify a time by configuring both Filter.2.Key and Filter.2.Value to query resources that were created before the time.

CreationEndTime
Filter.1.ValuestringNo

The value of filter 1 that is used to query resources. Set the value to a time. If you configure this parameter, you must also configure Filter.1.Key. Specify the time in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

2019-12-13T17:00Z
Filter.2.ValuestringNo

The value of filter 2 that is used to query resources. Set the value to a time. If you configure this parameter, you must also configure Filter.2.Key. Specify the time in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

2019-12-13T22:00Z
UsagestringNo

Specifies whether the snapshot has been used to create custom images or disks. Valid values:

  • image: The snapshot has been used to create custom images.
  • disk: The snapshot has been used to create disks.
  • image_disk: The snapshot has been used to create both custom images and data disks.
  • none: The snapshot has not been used to create custom images or disks.
none
SourceDiskTypestringNo

The type of the source disk. Valid values:

  • system: system disk
  • data: data disk
Note The value of this parameter is not case-sensitive.
Data
EncryptedbooleanNo

Specifies whether the snapshot is encrypted. Default value: false.

false
ResourceGroupIdstringNo

The resource group ID. If you configure this parameter to query resources, up to 1,000 resources that belong to the specified resource group can be displayed in the response.

Note Resources in the default resource group are displayed in the response regardless of whether you configure this parameter.
rg-bp67acfmxazb4p****
DryRunbooleanNo

Specifies whether to perform only a dry run, without performing the actual request. Valid values:

  • true: performs only a dry run. The system checks your AccessKey pair, the permissions of the RAM user, and the required parameters. If the request passes the dry run, the DryRunOperation error code is returned. Otherwise, an error message is returned.
  • false (default): performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
false
KMSKeyIdstringNo

The ID of the Key Management Service (KMS) key that is used for the data disk.

0e478b7a-4262-4802-b8cb-00d3fb40****
CategorystringNo

The category of the snapshot. Valid values:

  • Standard: normal snapshot
  • Flash: local snapshot

The local snapshot feature is replaced by the instant access feature. When you specify this parameter, take note of the following items:

  • If you have used local snapshots before December 14, 2020, you can use this parameter.
  • If you have not used local snapshots before December 14, 2020, you cannot use this parameter.
Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
Standard
Tagobject []No

The tags of the snapshot.

keystringNo

The key of tag N of the snapshot.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.key parameter to ensure future compatibility.
SnapshotTest
KeystringNo

The key of tag N of the snapshot. Valid values of N: 1 to 20

If a single tag is specified to query resources, up to 1,000 resources that have this tag added are returned. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added are returned. To query more than 1,000 resources with the specified tags, call the ListTagResources operation.

TestKey
ValuestringNo

The value of tag N of the snapshot. Valid values of N: 1 to 20.

TestValue
valuestringNo

The value of tag N of the snapshot.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure future compatibility.
SnapshotTest

Response parameters

ParameterTypeDescriptionExample
object
NextTokenstring

A pagination token. It can be used in the next request to retrieve a new page of results.

caeba0bbb2be03f84eb48b699f0a4883
PageSizeinteger

The number of entries per page.

10
PageNumberinteger

The page number.

1
RequestIdstring

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCountinteger

The total number of snapshots returned.

1
Snapshotsobject []

The information about the snapshots.

Statusstring

The state of the snapshot. Valid values:

  • progressing
  • accomplished
  • failed
accomplished
CreationTimestring

The time when the snapshot was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

2020-08-20T14:52:28Z
Progressstring

The progress of the snapshot creation task. Unit: percent (%).

100%
InstantAccessboolean

Indicates whether the instant access feature was enabled. Valid values:

  • true: The instant access feature was enabled. This feature can be enabled only for enhanced SSDs (ESSDs).
  • false: The instant access feature was disabled. The snapshot is a normal snapshot for which the instant access feature is disabled.
false
Availableboolean

Indicates whether the snapshot can be used to create or roll back disks. Valid values:

  • true
  • false
false
RemainTimeinteger

The remaining time required to create the snapshot. Unit: seconds.

38
SourceDiskSizestring

The capacity of the source disk. Unit: GiB.

40
RetentionDaysinteger

The retention period of the automatic snapshot. Unit: days.

30
SourceDiskTypestring

The type of the source disk. Valid values:

  • system
  • data
system
SourceStorageTypestring

The category of the source disk.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
disk
Usagestring

Indicates whether the snapshot has been used to create images or disks. Valid values:

  • image
  • disk
  • image_disk
  • none
image
LastModifiedTimestring

The time when the snapshot was last changed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

2020-08-25T14:18:09Z
Encryptedboolean

Indicates whether the snapshot is encrypted.

false
SnapshotTypestring

The type of snapshot. Valid values:

  • auto or timer: automatic snapshot.
  • user: manually created snapshot.
  • all: all snapshot types.
all
SourceDiskIdstring

The ID of the source disk. This parameter is retained even after the source disk is released.

d-bp67acfmxazb4ph****
SnapshotNamestring

The name of the snapshot. This parameter is returned only if a snapshot name was specified when the snapshot was created.

testSnapshotName
InstantAccessRetentionDaysinteger

Indicates the validity period of the instant access feature. When the specified period expires, the instant access feature is automatically disabled.

By default, the value of this parameter is the same as that of RetentionDays.

30
Descriptionstring

The description of the snapshot.

testDescription
SnapshotIdstring

The ID of the snapshot.

s-bp67acfmxazb4p****
ResourceGroupIdstring

The resource group ID to which the snapshot belongs.

rg-bp67acfmxazb4p****
Categorystring

The category of the snapshot.

Note This parameter will be removed in the future. We recommend that you use the InstantAccess parameter to ensure future compatibility.
standard
KMSKeyIdstring

The ID of the Key Management Service (KMS) key used for the data disk.

0e478b7a-4262-4802-b8cb-00d3fb40****
SnapshotSNstring

The serial number of the snapshot.

64472-116742336-61976****
ProductCodestring

The product code of the Alibaba Cloud Marketplace image.

jxsc000****
SourceSnapshotIdstring

The ID of the source snapshot.

s-bp67acfmxazb4p****
SourceRegionIdstring

The region ID of the source snapshot.

cn-hangzhou
Tagsobject []

The tags of the snapshot.

TagValuestring

The tag value of the snapshot.

TestValue
TagKeystring

The tag key of the snapshot.

TestKey

Examples

Sample success responses

JSONformat

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "PageSize": 10,
  "PageNumber": 1,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount": 1,
  "Snapshots": {
    "Snapshot": [
      {
        "Status": "accomplished",
        "CreationTime": "2020-08-20T14:52:28Z",
        "Progress": "100%",
        "InstantAccess": false,
        "Available": false,
        "RemainTime": 38,
        "SourceDiskSize": "40",
        "RetentionDays": 30,
        "SourceDiskType": "system",
        "SourceStorageType": "disk",
        "Usage": "image",
        "LastModifiedTime": "2020-08-25T14:18:09Z",
        "Encrypted": false,
        "SnapshotType": "all",
        "SourceDiskId": "d-bp67acfmxazb4ph****",
        "SnapshotName": "testSnapshotName",
        "InstantAccessRetentionDays": 30,
        "Description": "testDescription",
        "SnapshotId": "s-bp67acfmxazb4p****",
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "Category": "standard",
        "KMSKeyId": "0e478b7a-4262-4802-b8cb-00d3fb40****",
        "SnapshotSN": "64472-116742336-61976****",
        "ProductCode": "jxsc000****",
        "SourceSnapshotId": "s-bp67acfmxazb4p****",
        "SourceRegionId": "cn-hangzhou",
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        }
      }
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidTag.MismatchThe specified Tag.n.Key and Tag.n.Value are not match.The specified Tag.N.Key and Tag.N.Value parameters do not correspond to each other.
400InvalidTagCountThe specified tags are beyond the permitted range.The number of specified tags exceeds the upper limit.
403InvalidSnapshotIds.MalformedThe amount of specified specified snapshot Ids exceeds the limit.The specified snapshot ID is invalid.
403InvalidSnapshotCategory.MalformedThe specified Category is not valid.The specified Category parameter is invalid.
404InvalidFilterKey.NotFoundThe specified FilterKey is not found.The specified filter key does not exist.
404InvalidFilterValueThe specified FilterValue exceeds the limit.The specified filter value is invalid.
404InvalidUsageThe specifed Usage is not valid.The specified Usage parameter is invalid.
404InvalidSourceDiskTypeThe specifed SourceDiskType is not valid.-
404InvalidStatus.NotFoundThe specified Status is not found.The specified resource state does not exist.
404InvalidSnapshotType.NotFoundThe specfied SnapshotType is not found.-
404InvalidSnapshotLinkId.NotFoundThe specified snapshot link is not found.The specified snapshot chain does not exist.
500InternalErrorThe request processing has failed due to some unknown error.An internal error has occurred. Try again later.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-02-01The Error code has changed. The response structure of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
Output ParametersThe response structure of the API has changed.
2023-09-18The Error code has changed. The response structure of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 404 change
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 500
Output ParametersThe response structure of the API has changed.