DescribeSnapshots-阿里云帮助中心

Returns information about cloud disk snapshots, such as snapshot status, the estimated time remaining for snapshots in progress, and the retention period for automatic snapshots.

Operation description

The InstanceId, DiskId, and SnapshotIds request parameters are optional and used to filter results. A logical AND operator combines these parameters.

When you call this operation using Alibaba Cloud CLI, values for request parameters of different data types must follow specific formatting rules. For more information, see CLI parameter formats.

Request examples:

Query the snapshots of all cloud disks that are attached to an ECS instance in the China (Hangzhou) region

RegionId:  cn-hangzhou,   // Specify the China (Hangzhou) region.
InstanceId:  i-bp1fh7by6d9mw7zr****   // Specify the ID of the instance to query.

Query the snapshots of a specific cloud disk in the China (Hangzhou) region

RegionId:  cn-hangzhou,   // Specify the China (Hangzhou) region.
DiskId:   d-bp10e7ej8z743dmu****   // Specify the ID of the cloud disk to query.

Query two snapshots by snapshot ID in the China (Hangzhou) region

RegionId:  cn-hangzhou,   // Specify the China (Hangzhou) region.
SnapshotIds:   ["d-bp10e7ej8z743dmu****", "s-bp19vd1lorzgzt2s****"]   // Specify an array of snapshot IDs to query.

Query snapshots created after a specific point in time in the China (Hangzhou) region

RegionId:  cn-hangzhou,   // Specify the China (Hangzhou) region.
Filter.1.Key:   CreationStartTime,   // The filter key. This example uses CreationStartTime to filter by creation time.
Filter.1.Value:   2024-11-27T00:00Z

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:DescribeSnapshots

get

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/*

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}

None

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	No	The ID of the instance. This operation returns snapshots of disks that are attached to the specified instance.	i-bp67acfmxazb4p****
DiskId	string	No	The ID of the disk.	d-bp67acfmxazb4p****
SnapshotLinkId	string	No	The ID of the snapshot chain.	sl-bp1grgphbcc9brb5****
RegionId	string	Yes	The ID of the region where the snapshot resides. You can call the DescribeRegions operation to obtain the latest list of Alibaba Cloud regions.	cn-hangzhou
SnapshotIds	string	No	A JSON array of snapshot IDs. You can specify up to 100 snapshot IDs.	["s-bp67acfmxazb4p**", "s-bp67acfmxazb5p", … "s-bp67acfmxazb6p**"]
PageNumber	integer	No	Note This parameter is deprecated. Use `NextToken` and `MaxResults` for pagination instead.	1
PageSize	integer	No	Note This parameter is deprecated. Use `NextToken` and `MaxResults` for pagination instead.	10
NextToken	string	No	The token used to start the next page of results. To retrieve the next page, set this parameter to the `NextToken` value from the previous response.	caeba0bbb2be03f84eb48b699f0a4883
MaxResults	integer	No	The number of entries to return on each page. Maximum value: 100. Default value: 10.	10
SnapshotName	string	No	The name of the snapshot.	testSnapshotName
Status	string	No	The status of the snapshot. Valid values: `progressing`: The snapshot is being created. `accomplished`: The snapshot has been created. `failed`: The snapshot failed to be created. `all` (Default): All snapshot statuses.	all
SnapshotType	string	No	The method used to create the snapshot. Valid values: `auto`: Created by an automatic snapshot policy. `user`: Created manually. `all` (Default): All snapshot creation methods.	all
Filter.1.Key	string	No	The filter key. Set to `CreationStartTime` to query for resources created after a specific point in time.	CreationStartTime
Filter.2.Key	string	No	The filter key. Set to `CreationEndTime` to query for resources created before a specific point in time.	CreationEndTime
Filter.1.Value	string	No	The filter value. This parameter must be used with `Filter.1.Key`. The time must be in the `yyyy-MM-ddTHH:mmZ` format and in UTC.	2019-12-13T17:00Z
Filter.2.Value	string	No	The filter value. This parameter must be used with `Filter.2.Key`. The time must be in the `yyyy-MM-ddTHH:mmZ` format and in UTC.	2019-12-13T22:00Z
Usage	string	No	Indicates whether the snapshot has been used to create an image or a disk. Valid values: `image`: The snapshot has been used to create a custom image. `disk`: The snapshot has been used to create a disk. `image_disk`: The snapshot has been used to create both a custom image and a disk. `none`: The snapshot is not in use.	none
SourceDiskType	string	No	The type of the snapshot's source disk. Valid values: `system`: system disk `data`: data disk Note This parameter is not case-sensitive.	system
Encrypted	boolean	No	Specifies whether to filter encrypted snapshots. Default value: false.	false
ResourceGroupId	string	No	The ID of the resource group. If you use this parameter to filter resources, the number of resources cannot exceed 1,000. Note You cannot use this parameter to filter resources in the default resource group.	rg-bp67acfmxazb4p****
DryRun	boolean	No	Specifies whether to perform a dry run. `true`: Performs a dry run to check the request's validity and permissions without executing the operation. A successful dry run returns the `DryRunOperation` error code. A failed dry run returns a standard error message. `false` (Default): Sends a standard request and executes the operation. A successful request returns a 2xx HTTP status code and the results.	false
KMSKeyId	string	No	The ID of the KMS key used for the snapshot.	0e478b7a-4262-4802-b8cb-00d3fb40****
Category	string	No	The category of the snapshot. Valid values: `Standard`: standard snapshot If you used local snapshots before December 14, 2020, you can continue to use this parameter. If you did not use local snapshots before December 14, 2020, you cannot use this parameter. `archive`: archive snapshot For more information, see Notice: Alibaba Cloud Snapshot Service Upgrade and New Billing Items on December 14.	Standard
Tag	array<object>	No	The tags.
	object	No
key	string	No	资源的标签键。 Note 为提高兼容性，建议您尽量使用 Tag.N.Key 参数。	SnapshotTest
Key	string	No	资源的标签键。 Note 为提高兼容性，建议您尽量使用 Tag.N.Key 参数。	TestKey
Value	string	No	快照的标签值。N 的取值范围：1~20。	TestValue
value	string	No	快照的标签值。N 的取值范围：1~20。	SnapshotTest

Response elements

Element	Type	Description	Example
	object
NextToken	string	The token to retrieve the next page of results.	caeba0bbb2be03f84eb48b699f0a4883
PageSize	integer	Note This parameter is deprecated. Use the `NextToken` and `MaxResults` parameters to paginate the results.	10
PageNumber	integer	Note This parameter is deprecated. Use the `NextToken` and `MaxResults` parameters to paginate the results.	1
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCount	integer	The total number of snapshots. Note When you use the`MaxResults` and `NextToken` parameters for pagination, the `TotalCount` value is not reliable.	1
Snapshots	object	Details of the snapshots.
Snapshot	array<object>	The details of the snapshots.
	array<object>
Status	string	The status of the snapshot. Valid values: `progressing`: The snapshot is being created. `accomplished`: The snapshot is complete. `failed`: Snapshot creation failed.	accomplished
CreationTime	string	The UTC time when the snapshot was created, in ISO 8601 format: `yyyy-MM-ddTHH:mm:ssZ`.	2020-08-20T14:52:28Z
Progress	string	The progress of the snapshot creation, as a percentage.	100%
InstantAccess	boolean	Indicates whether the instant access feature is enabled. Valid values: `true`: The instant access feature is enabled. This feature is enabled by default for ESSD and ESSD Entry cloud disks. `false`: The instant access feature is disabled. Note This parameter is deprecated. Standard snapshots of ESSD cloud disks now support the instant access feature by default. This feature requires no configuration and incurs no extra fees.	false
Available	boolean	Indicates whether the snapshot can be used to create disks, roll back disks, or be shared. Valid values: `true`: The snapshot is available. `false`: The snapshot is not available.	false
RemainTime	integer	The time remaining, in seconds, until the snapshot creation is complete.	38
SourceDiskSize	string	The capacity of the source disk. Unit: GiB.	40
RetentionDays	integer	The retention period in days for an automatic snapshot.	30
SourceDiskType	string	The category of the source disk. Valid values: `system`: system disk `data`: data disk	system
SourceStorageType	string	The type of the source disk. Note This parameter is deprecated. For better compatibility, we recommend using other parameters.	disk
Usage	string	Indicates how the snapshot was used. Valid values: `image`: The snapshot was used to create a custom image. `disk`: The snapshot was used to create a disk. `image_disk`: The snapshot was used to create a custom image and a data disk. `none`: The snapshot is unused.	image
LastModifiedTime	string	The UTC time when the snapshot was last modified, in ISO 8601 format: `yyyy-MM-ddTHH:mm:ssZ`.	2020-08-25T14:18:09Z
Encrypted	boolean	Indicates whether the snapshot is encrypted. Valid values: `true`: The snapshot is encrypted. `false`: The snapshot is not encrypted.	false
SnapshotType	string	The method used to create the snapshot. Valid values: `auto` or `timer`: The snapshot was created by an automatic snapshot policy. `user`: The snapshot was manually created. `all`: All creation methods.	all
SourceDiskId	string	The ID of the source disk. This parameter is retained even if the source disk has been released.	d-bp67acfmxazb4ph****
SnapshotName	string	The name of the snapshot. This parameter is returned only if a name was provided at creation.	testSnapshotName
InstantAccessRetentionDays	integer	The retention period of the instant access feature, in days. The feature is automatically disabled after this period expires. By default, this value is the same as `RetentionDays`. Note This parameter is deprecated. Standard snapshots of ESSD cloud disks now support the instant access feature by default. This feature requires no configuration and incurs no extra fees.	30
Description	string	The description of the snapshot.	testDescription
SnapshotId	string	The ID of the snapshot.	s-bp67acfmxazb4p****
RegionId	string	The ID of the snapshot's region.	cn-hangzhou
ResourceGroupId	string	The ID of the resource group.	rg-bp67acfmxazb4p****
Category	string	The category of the snapshot. Valid values: `standard`: standard snapshot. `Flash`: local snapshot. This value is deprecated. The local snapshot feature was replaced by the instant access feature. `archive`: archive snapshot.	standard
KMSKeyId	string	The ID of the KMS key used to encrypt the snapshot.	0e478b7a-4262-4802-b8cb-00d3fb40****
SnapshotSN	string	The serial number of the snapshot.	64472-116742336-61976****
ProductCode	string	The product code inherited from the Marketplace image.	jxsc000****
SourceSnapshotId	string	The ID of the source snapshot.	s-bp67acfmxazb4p****
SourceRegionId	string	The region of the source snapshot.	cn-hangzhou
FullSnapshotSizeInBytes	integer	The size of the full snapshot in bytes.	65535
Tags	object	The tags of the snapshot.
Tag	array<object>	Details of the tags.
	object
TagValue	string	The value of the tag.	TestValue
TagKey	string	The key of the tag.	TestKey
SnapshotLinkId	string	The ID of the snapshot chain associated with the snapshot.	sl-bp1grgphbcc9brb5****

Examples

Success response

JSON format

{
  "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",
        "FullSnapshotSizeInBytes": 65535,
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        },
        "SnapshotLinkId": "sl-bp1grgphbcc9brb5****"
      }
    ]
  }
}

Error response

JSON format

{
  "PageNumber": 1,
  "PageSize": 2,
  "RequestId": "659F91C6-1949-43B0-90C4-B6342CA757D5",
  "Snapshots": {
    "Snapshot": [
      {
        "CreationTime": "2015-07-30T05:00:14Z",
        "Progress": "100%",
        "SnapshotId": "s-943ypfgic",
        "SnapshotName": "auto_20150730_3",
        "SourceDiskId": "d-944qyqjfa",
        "SourceDiskSize": 20,
        "SourceDiskType": "system",
        "Status": "accomplished",
        "Usage": "none"
      },
      {
        "CreationTime": "2015-07-30T05:00:14Z",
        "Progress": "100%",
        "SnapshotId": "s-94osg320e",
        "SnapshotName": "auto_20150730_3",
        "SourceDiskId": "d-94j355jsq",
        "SourceDiskSize": 20,
        "SourceDiskType": "system",
        "Status": "accomplished",
        "Usage": "none"
      }
    ]
  },
  "TotalCount": 36
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidTag.Mismatch	The 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.
400	InvalidTagCount	The specified tags are beyond the permitted range.	The number of specified tags exceeds the upper limit.
500	InternalError	The request processing has failed due to some unknown error.
403	InvalidSnapshotIds.Malformed	The amount of specified specified snapshot Ids exceeds the limit.
403	InvalidSnapshotCategory.Malformed	The specified Category is not valid.	The specified Category parameter is invalid.
403	InvalidCategory.SnapshotLinkMismatch	The specified category does not match the actual category of the snapshot link.	The specified category does not match the snapshot chain.
404	InvalidFilterKey.NotFound	The specified FilterKey is not found.	The specified filter key does not exist.
404	InvalidFilterValue	The specified FilterValue exceeds the limit.	The specified filter value is invalid.
404	InvalidUsage	The specifed Usage is not valid.	The specified Usage parameter is invalid.
404	InvalidSourceDiskType	The specifed SourceDiskType is not valid.
404	InvalidStatus.NotFound	The specified Status is not found.
404	InvalidSnapshotType.NotFound	The specfied SnapshotType is not found.
404	InvalidSnapshotLinkId.NotFound	The specified snapshot link is not found.	The specified snapshot chain does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.