All Products
Search
Document Center

Elastic Compute Service:DescribeSnapshotGroups

Last Updated:Oct 22, 2026

Queries the information about one or more snapshot-consistent groups, such as the status, the associated instance ID, and the snapshot creation progress.

Operation description

InstanceId, SnapshotGroupId.N, and Status.N are not required request parameters, but you can use them to build filter logic. The logical relationship between these parameters is AND.

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:DescribeSnapshotGroups

get

SnapshotGroup

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

SnapshotGroup

acs:ecs:{#regionId}:{#accountId}:snapshotgroup/{#snapshotgroupId}

None None

Request parameters

Parameter

Type

Required

Description

Example

RegionId

string

Yes

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

cn-hangzhou

InstanceId

string

No

The instance ID.

i-j6ca469urv8ei629****

Name

string

No

The name of the snapshot-consistent group.

testName

NextToken

string

No

The query token. Set the value to the NextToken value returned in the last API call.

caeba0bbb2be03f84eb48b699f0a4883

MaxResults

integer

No

The number of entries per page for a paged query.

Maximum value: 100.

Default value: 10.

10

SnapshotGroupId

array

No

The IDs of the snapshot-consistent groups. Valid values of N: 1 to 10.

ssg-j6ciyh3k52qp7ovm****

string

No

The IDs of the snapshot-consistent groups. Valid values of N: 1 to 10.

ssg-j6ciyh3k52qp7ovm****

Status

array

No

The status of the snapshot-consistent group. Valid values of N: 1 to 3. Valid values:

  • progressing: The snapshot-consistent group is being created.

  • accomplished: The snapshot-consistent group is created.

  • failed: The snapshot-consistent group fails to be created.

accomplished

string

No

The status of the snapshot-consistent group. Valid values of N: 1 to 3. Valid values:

  • progressing: The snapshot-consistent group is being created.

  • accomplished: The snapshot-consistent group is created.

  • failed: The snapshot-consistent group fails to be created.

accomplished

AdditionalAttributes

array

No

This parameter is not available.

hide

string

No

Note

This parameter is not available.

null

Tag

array<object>

No

The tags of the snapshot-consistent group.

object

No

The tags of the snapshot-consistent group.

Key

string

No

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

TestKey

Value

string

No

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

TestValue

ResourceGroupId

string

No

The ID of the resource group to which the snapshot-consistent group belongs.

rg-bp67acfmxazb4p****

Response elements

Element

Type

Description

Example

object

NextToken

string

The token for the next query.

Note

If this parameter is empty, no more data is returned.

caeba0bbb2be03f84eb48b699f0a4883

RequestId

string

The request ID.

3F9A4CC4-362F-469A-B9EF-B3204EF8AA3A

SnapshotGroups

object

SnapshotGroup

array<object>

The array of snapshot-consistent group information.

array<object>

The details of the snapshot-consistent group.

CreationTime

string

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

2021-03-23T10:58:48Z

Description

string

The description.

This is description.

InstanceId

string

Instance ID of the instance to which the snapshot-consistent group belongs. This parameter is returned only when all disk snapshots in the snapshot-consistent group belong to the same instance. If multiple disk snapshots in the snapshot-consistent group belong to different ECS instances, you can view instance ID of the instance to which a single snapshot belongs by using the Snapshots.Snapshot.Tags.* parameter in the response.

i-j6ca469urv8ei629****

Name

string

The name of the snapshot-consistent group.

testName

ProgressStatus

string

Note

This parameter is not available.

null

ResourceGroupId

string

The ID of the resource group to which the snapshot-consistent group belongs.

rg-bp67acfmxazb4p****

SnapshotGroupId

string

The ID of the snapshot-consistent group.

ssg-j6ciyh3k52qp7ovm****

Snapshots

object

Snapshot

array<object>

The array of snapshot details in the snapshot consistency group.

array<object>

Available

boolean

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

  • true: The snapshot is available.

  • false: The snapshot is unavailable.

false

InstantAccess

boolean

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

  • true: Enabled. This feature is enabled by default for ESSD (standard SSD) cloud disks.

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

Note

[Deprecated] Standard snapshots of ESSD (standard SSD) cloud disks are upgraded to instant access by default. You do not need to configure this parameter, and no additional fees are incurred.

true

InstantAccessRetentionDays

integer

The retention period of the instant access feature when it is active. After the retention period expires, the snapshot undergoes automatic release.

Note

[Deprecated] Standard snapshots of ESSD (standard SSD) cloud disks are upgraded to instant access by default. You do not need to configure this parameter, and no additional fees are incurred.

3

Progress

string

The creation progress of the snapshot. Unit: %.

100%

SnapshotId

string

The ID of the snapshot.

s-j6cbzmrlbf09w72q****

SourceDiskId

string

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

d-j6c3ogynmvpi6wy7****

SourceDiskType

string

The type of the source cloud disk. Valid values:

  • system: system cloud disk.

  • data: data cloud disk.

system

Tags

object

Tag

array<object>

The tags of each snapshot in the snapshot consistency group. By default, the tags contain the source information of the snapshot.

object

Key

string

The key of the tag for each snapshot in the snapshot consistency group. The default values of Key and Value provide the source information of the snapshot.

acs:ecs:createFrom

Value

string

The value of the tag for each snapshot in the snapshot consistency group. The default values of Key and Value provide the source information of the snapshot.

i-bp11qm0o3dk4iuc****

Status

string

The status of the snapshot-consistent group. Valid values:

  • progressing: The snapshot-consistent group is being created.

  • accomplished: The snapshot-consistent group is created.

  • failed: The snapshot-consistent group fails to be created.

accomplished

Tags

object

Tag

array<object>

The tags of the snapshot-consistent group.

object

Key

string

The tag key of the snapshot-consistent group.

TestKey

Value

string

The tag value of the snapshot-consistent group.

TestValue

Examples

Success response

JSON format

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "RequestId": "3F9A4CC4-362F-469A-B9EF-B3204EF8AA3A",
  "SnapshotGroups": {
    "SnapshotGroup": [
      {
        "CreationTime": "2021-03-23T10:58:48Z",
        "Description": "This is description.",
        "InstanceId": "i-j6ca469urv8ei629****",
        "Name": "testName",
        "ProgressStatus": "null",
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "SnapshotGroupId": "ssg-j6ciyh3k52qp7ovm****",
        "Snapshots": {
          "Snapshot": [
            {
              "Available": false,
              "InstantAccess": true,
              "InstantAccessRetentionDays": 3,
              "Progress": "100%",
              "SnapshotId": "s-j6cbzmrlbf09w72q****",
              "SourceDiskId": "d-j6c3ogynmvpi6wy7****",
              "SourceDiskType": "system",
              "Tags": {
                "Tag": [
                  {
                    "Key": "acs:ecs:createFrom",
                    "Value": "i-bp11qm0o3dk4iuc****"
                  }
                ]
              }
            }
          ]
        },
        "Status": "accomplished",
        "Tags": {
          "Tag": [
            {
              "Key": "TestKey",
              "Value": "TestValue"
            }
          ]
        }
      }
    ]
  }
}

Error codes

HTTP status code

Error code

Error message

Description

400 Duplicate.TagKey The parameter Tag.N.Key contains duplicate values. Please remove the duplicate tag keys and try again.
400 InvalidParameter.NextToken The specified parameter NextToken is not valid. Ensure you provide the NextToken value returned in the previous response.
403 InvalidSnapshotGroupId.MustBeOne The size of SnapshotGroupIds must be one when AdditionalAttributes has SNAPSHOT_GROUP_PROGRESS_STATUS.
403 InvalidStatus.ValueNotSupported The specified parameter status is not valid. The expected status is progressing; accomplished or failed.
404 InvalidRegionId.NotFound The RegionId provided does not exist in our records. Region information error
404 InvalidInstanceId.NotFound The InstanceId provided does not exist in our records.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.