All Products
Search
Document Center

Elastic Compute Service:DescribeSnapshots

Last Updated:Sep 29, 2024

Queries all snapshots of an Elastic Compute Service (ECS) instance or a disk. When you call this operation, you can specify parameters, such as InstanceId, DiskId, SnapshotLinkId, and Status, in the request.

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

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:DescribeSnapshotsget
  • Snapshot
    acs:ecs:{#regionId}:{#accountId}:snapshot/*
  • Snapshot
    acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}
    none
none

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. Pages start 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 source disk type of the snapshot. Valid values:

  • system: system disk.
  • data: data disk.
Note The value of this parameter is case-insensitive.
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
Tagarray<object>No

The tags of the snapshot.

objectNo
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
Snapshotsarray<object>

The information about the snapshots.

Snapshotobject
Statusstring

The status 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 is enabled. Valid values:

  • true: The instant access feature is enabled. By default, the instant access feature is enabled for Enterprise SSDs (ESSDs).
  • false: The instant access feature is 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 a disk. Valid values:

  • true
  • false
false
RemainTimeinteger

The amount of 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 was used to create images or disks. Valid values:

  • image
  • disk
  • image_disk
  • none
image
LastModifiedTimestring

The time when the snapshot was last modified. 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 the snapshot. Valid values:

  • auto or timer: automatic snapshot
  • user: manual 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 the value of RetentionDays.

Note This parameter is no longer used. The normal snapshots of ESSDs are upgraded to support the instant access feature by default. No additional configurations are required to enable the feature and you are not charged for the feature. For more information, see Use the instant access feature.
30
Descriptionstring

The description of the snapshot.

testDescription
SnapshotIdstring

The ID of the snapshot.

s-bp67acfmxazb4p****
RegionIdstring

The region ID of the snapshot.

cn-hangzhou
ResourceGroupIdstring

The ID of the resource group 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 InstantAccess to ensure future compatibility.
standard
KMSKeyIdstring

The ID of the 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
SnapshotLinkIdstring

The ID of the snapshot chain that is associated with the snapshot.

sl-bp1grgphbcc9brb5****
Tagsarray<object>

The tags of the snapshot.

Tagobject
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****",
        "RegionId": "cn-hangzhou",
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "Category": "standard",
        "KMSKeyId": "0e478b7a-4262-4802-b8cb-00d3fb40****",
        "SnapshotSN": "64472-116742336-61976****",
        "ProductCode": "jxsc000****",
        "SourceSnapshotId": "s-bp67acfmxazb4p****",
        "SourceRegionId": "cn-hangzhou",
        "SnapshotLinkId": "sl-bp1grgphbcc9brb5****",
        "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-05-22The Error code has changed. The response structure of the API has changedView Change Details
2024-02-01The Error code has changed. The response structure of the API has changedView Change Details
2023-09-18The Error code has changed. The response structure of the API has changedView Change Details