All Products
Search
Document Center

Elastic Compute Service:DescribeSnapshots

Last Updated:Oct 16, 2026

Queries the list of snapshots for a cloud disk, including information such as the snapshot status, the remaining time for snapshot creation, and the retention period of automatic snapshots.

Operation description

InstanceId, DiskId, and SnapshotIds are not required request parameters, but you can use them to build filter logic. The logical relationship among these parameters is AND.

When you invoke API operations by using Cloud Assistant CLI, request parameter values of different data types must follow specific format requirements. For details, see CLI parameter format description.

Request examples:

Query the list of snapshots for all cloud disks of an ECS instance in the China (Hangzhou) region

RegionId:  cn-hangzhou,   // Settings for the China (Hangzhou) region.
InstanceId:  i-bp1fh7by6d9mw7zr****   // Settings for the instance ID to be queried.

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

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

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

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

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

RegionId:  cn-hangzhou,   // Set the region to China (Hangzhou).
Filter.1.Key:   CreationStartTime,   // Set the array of snapshot IDs to be queried.
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 None

Request parameters

Parameter

Type

Required

Description

Example

InstanceId

string

No

The instance ID. This parameter specifies the instance whose cloud disk snapshots you want to query.

i-bp67acfmxazb4p****

DiskId

string

No

The ID of the cloud disk.

d-bp67acfmxazb4p****

SnapshotLinkId

string

No

The ID of the snapshot chain.

sl-bp1grgphbcc9brb5****

RegionId

string

Yes

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

cn-hangzhou

SnapshotIds

string

No

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

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

PageNumber

integer

No

Note

This parameter will be offline soon. We recommend that you use the NextToken and MaxResults parameters to perform paging for paged query operations.

1

PageSize

integer

No

Note

This parameter will be offline soon. We recommend that you use the NextToken and MaxResults parameters to perform paging for paged query operations.

10

NextToken

string

No

The pagination token. Obtain the token from the response of the previous request.

caeba0bbb2be03f84eb48b699f0a4883

MaxResults

integer

No

The number of entries per page during paging for a paged query. 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 is created.

  • failed: The snapshot fails to be created.

  • all: All statuses. This is the default value.

all

SnapshotType

string

No

The snapshot creation type. Valid values:

  • auto: automatic creation.

  • user: manual creation.

  • all: all snapshot creation types. This is the default value.

all

Filter.1.Key

string

No

The filter key used to query resources. The value must be CreationStartTime. If you specify both Filter.1.Key and Filter.1.Value, you can query the resources created after the specified point in time.

CreationStartTime

Filter.2.Key

string

No

The filter key used to query resources. The value must be CreationEndTime. If you specify both Filter.2.Key and Filter.2.Value, you can query the resources created before the specified point in time.

CreationEndTime

Filter.1.Value

string

No

The filter value used to query resources. If you specify this parameter, you must also specify the Filter.1.Key parameter. The value must be in the yyyy-MM-ddTHH:mmZ format and in UTC+0.

2019-12-13T17:00Z

Filter.2.Value

string

No

The filter value used to query resources. If you specify this parameter, you must also specify the Filter.2.Key parameter. The value must be in the yyyy-MM-ddTHH:mmZ format and in UTC+0.

2019-12-13T22:00Z

Usage

string

No

The usage of the snapshot. Valid values:

  • image: The snapshot is used to create a custom image.

  • disk: The snapshot is used to create a cloud disk.

  • image_disk: The snapshot is used to create a data disk and a custom image.

  • none: The snapshot is not used.

none

SourceDiskType

string

No

The type of the source cloud disk. Valid values:

  • system: The source cloud disk is a system disk.

  • data: The source cloud disk is a data disk.

Note

The value 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. When you use this parameter to filter resources, the resource count cannot exceed 1,000.

Note

Filtering by the default resource group is not supported.

rg-bp67acfmxazb4p****

DryRun

boolean

No

Specifies whether to perform only a dry run on the request. Valid values:

  • true: send a check request without querying the resource status. The system checks whether your AccessKey pair is valid, whether the Resource Access Management (RAM) user has the required authorization, and whether the required parameters are specified. If the check fails, the corresponding error is returned. If the check succeeds, the DryRunOperation error code is returned.

  • false (default): send a Normal request. If the check succeeds, a 2xx HTTP status code is returned and the resource status is queried.

false

KMSKeyId

string

No

The ID of the KMS key used for the data disk.

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

Category

string

No

The snapshot type. Valid values:

  • Standard: standard snapshot.

  • Flash: local snapshot. This parameter value will be deprecated. Local snapshots are replaced by the snapshot instant active feature. The metric description of this parameter is as follows:
    • If you used local snapshots before December 14, 2020, you can use this parameter for Normal use.

    • If you did not use local snapshots before December 14, 2020, you cannot use this parameter.

  • archive: archive snapshot.

Standard

Tag

array<object>

No

The list of tags.

object

No

key

string

No

The tag key of the resource.

Note

To improve compatibility, use the Tag.N.Key parameter.

SnapshotTest

Key

string

No

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

If you use a single tag to filter resources, the resource count of queried resources cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of queried resources that attach to all the specified tags cannot exceed 1,000. If the resource count exceeds 1,000, use the ListTagResources operation to query the resources.

TestKey

Value

string

No

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

TestValue

value

string

No

The tag value of the resource.

Note

To improve compatibility, use the Tag.N.Value parameter.

SnapshotTest

Response elements

Element

Type

Description

Example

object

NextToken

string

The pagination token for the next query.

caeba0bbb2be03f84eb48b699f0a4883

PageSize

integer

Note

This parameter will soon be deprecated. Use NextToken and MaxResults for paged queries.

10

PageNumber

integer

Note

This parameter will soon be deprecated. Use NextToken and MaxResults for paged queries.

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 paged queries, the returned value of TotalCount is invalid.

1

Snapshots

object

Snapshot

array<object>

The snapshot details.

array<object>

Status

string

The snapshot status. Valid values:

  • progressing: The snapshot is being created.

  • accomplished: The snapshot is created.

  • failed: The snapshot creation failed.

accomplished

CreationTime

string

The creation time. The time is displayed in UTC and follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format.

2020-08-20T14:52:28Z

Progress

string

The snapshot creation progress, in percentage.

100%

InstantAccess

boolean

Indicates whether the snapshot instant access feature is enabled. Valid values:

  • true: enabled. This feature is enabled by default for enterprise SSDs and ESSD Entry disks.

  • false: disabled. The snapshot is a standard snapshot for which the instant access feature is not enabled.

Note

[Deprecated] This parameter is deprecated. Standard snapshots of enterprise SSDs are upgraded to instant access by default. No additional configuration or fees are required.

false

Available

boolean

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

  • true: yes

  • false: no

false

RemainTime

integer

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

38

SourceDiskSize

string

The capacity of the source disk. Unit: GiB.

40

RetentionDays

integer

The retention period of the automatic snapshot, in days.

30

SourceDiskType

string

The type of the source disk. Valid values:

  • system

  • data

system

SourceStorageType

string

The storage type of the source disk.

Note

This parameter will soon be deprecated. To improve compatibility, use other parameters instead.

disk

Usage

string

The usage of the snapshot. Valid values:

  • image: custom image

  • disk: disk

  • image_disk: custom image and data disk

  • none: not used

image

LastModifiedTime

string

The last modification time of the snapshot. The time is displayed in UTC and follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format.

2020-08-25T14:18:09Z

Encrypted

boolean

Indicates whether the snapshot is encrypted. Valid values:

  • true: yes

  • false: no

false

SnapshotType

string

The automatic creation type. Valid values:

  • auto or timer: automatic snapshot

  • user: manual snapshot

  • all: all automatic creation types

all

SourceDiskId

string

The ID of the source disk. If the source disk of the snapshot has been released, this field is still retained.

d-bp67acfmxazb4ph****

SnapshotName

string

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

testSnapshotName

InstantAccessRetentionDays

integer

The retention period of the snapshot instant access feature. After the retention period expires, the snapshot instant access feature is automatically disabled.

Default value: the value of the RetentionDays parameter.

Note

[Deprecated] This parameter is deprecated. Standard snapshots of enterprise SSDs are upgraded to instant access by default. No additional configuration or fees are required.

30

Description

string

The description.

testDescription

SnapshotId

string

The snapshot ID.

s-bp67acfmxazb4p****

RegionId

string

The region ID of the snapshot.

cn-hangzhou

ResourceGroupId

string

The resource group ID.

rg-bp67acfmxazb4p****

Category

string

The snapshot type. Valid values:

  • Standard: standard snapshot

  • Flash: local snapshot. This value will soon be deprecated. Local snapshots are replaced by the snapshot instant access feature.

  • archive: archive snapshot

standard

KMSKeyId

string

The ID of the KMS key used for the data disk.

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

SnapshotSN

string

The snapshot serial number.

64472-116742336-61976****

ProductCode

string

The product code inherited from the Alibaba Cloud Marketplace image.

jxsc000****

SourceSnapshotId

string

The source snapshot.

s-bp67acfmxazb4p****

SourceRegionId

string

The region of the source snapshot.

cn-hangzhou

FullSnapshotSizeInBytes

integer

The full size of the snapshot. Unit: bytes.

65535

Tags

object

Tag

array<object>

The tags.

object

TagValue

string

The tag value of the snapshot.

TestValue

TagKey

string

The tag key of the snapshot.

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 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.