All Products
Search
Document Center

Elastic Compute Service:CreateSnapshot

Last Updated:Oct 22, 2026

Creates a snapshot for a cloud disk.

Operation description

Local snapshots have been replaced by the snapshot instant access feature. The metric description is as follows:

  • If you used local snapshots before December 14, 2020, Normal use of the Category parameter is allowed.

  • If you did not use local snapshots before December 14, 2020, no additional configuration is required. Snapshots created for enterprise SSD series disks (enterprise SSD, ESSD AutoPL, ESSD Entry, and regional enterprise SSD) are active by default after creation, and both the manual snapshot and automatic snapshot features are supported. The InstantAccess, InstantAccessRetentionDays, and DisableInstantAccess parameters related to the instant access feature no longer take effect in API operations. The DescribeSnapshots and DescribeSnapshotGroups API operations add the Available response parameter to describe the active status of snapshots.

Before you begin:

  • The snapshot feature is activated. For more information, see Activate the snapshot feature.

  • The cloud disk must be in the In Use or Available state. Take note of the following items based on the disk state:

    • If the cloud disk is in the In Use state, the instance must be in the Running or Stopped state.

    • If the cloud disk is in the Available state, make sure that the cloud disk was previously attached to an ECS instance. You cannot create snapshots for cloud disks that have never been attached to an ECS instance.

    • When a cloud disk is used to create a dynamic extended volume or a RAID array, we recommend that you use a snapshot-consistent group and enable application-consistent snapshots to back up data. A snapshot-consistent group ensures the chronological consistency of data written to cloud disks and guarantees crash consistency in scenarios where a business system spans multiple cloud disks. For more information, see Create a snapshot-consistent group and Create an application-consistent snapshot.

When you create a snapshot, take note of the following items:

  • Avoid creating snapshots during peak business hours. When a snapshot is being created, the I/O performance of the disk decreases by less than 10%, and the read and write performance may experience brief instantaneous slowdowns.

  • If the snapshot creation is not complete, the snapshot cannot be used to create a custom image (CreateImage).

  • During snapshot creation, no backup of incremental data generated by operations on the disk is saved to the snapshot.

  • If the disk is attached to an ECS instance, do not change the instance status during snapshot creation, such as stopping or restarting the ECS instance. Otherwise, it results in a failed snapshot creation.

  • You cannot perform scale-out on a disk while a snapshot is being created for it. Wait until the snapshot is created before you execute scale-out operations.

  • You can create snapshots for cloud disks in the Expired (Expired) state. If a cloud disk reaches its expiration and release time while a snapshot is being created, the snapshot in the Creating (Creating) state is deleted when the cloud disk is released.

  • After a snapshot is created, the system bills you based on the snapshot size in each region. For more information, see Snapshot billing.

  • You cannot create snapshots for a specified cloud disk in the following scenarios:

    • The number of manual snapshots retained for the cloud disk reaches the upper limit. For more information, see Snapshot limits.

    • Snapshot creation has concurrency limits. Exceeding the limits causes the creation to fail. For more information, see Snapshot limits.

    • If the response to a query for ECS instance information contains {"OperationLocks": {"LockReason" : "security"}}, all operations are prohibited.

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

create

*Disk

acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}

*Snapshot

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

None None

Request parameters

Parameter

Type

Required

Description

Example

DiskId

string

Yes

The ID of the cloud disk. You can call the DescribeDisks operation and filter by InstanceId to query the cloud disks attached to the instance. The cloud disk used to create a snapshot must be in the In Use or Available state. An available cloud disk must have been previously attached to an ECS instance.

d-bp1s5fnvk4gn2tws0****

SnapshotName

string

No

The name of the snapshot. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and can contain Unicode letters (including English and Chinese characters) and ASCII digits (0-9). It can contain colons (:), underscores (_), periods (.), and hyphens (-).

Note

It cannot start with http:// or https://. To prevent name conflicts with automatic snapshots, it cannot start with auto.

testSnapshotName

Description

string

No

The description of the snapshot. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

Default value: empty.

testDescription

RetentionDays

integer

No

Settings for the retention period of the snapshot. Unit: days. Valid values: 1 to 65536. The snapshot is subject to automatic release when the retention period expires.

Default value: empty, which indicates that the snapshot is not subject to automatic release.

30

Category

string

No

The snapshot type. Valid values:

  • Standard: standard snapshot.

  • Flash: local snapshot.

Note

This parameter is about to be deprecated. Standard snapshots for enterprise SSD disks (excluding standard SSD) have been upgraded to active by default. No additional configuration is required, and no extra costs are incurred.

Standard

ClientToken

string

No

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that the value is unique among different requests. The ClientToken parameter can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see Ensure idempotence.

123e4567-e89b-12d3-a456-426655440000

ResourceGroupId

string

No

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

rg-bp67acfmxazb4p****

InstantAccess

boolean

No

Specifies whether to enable the snapshot instant access feature. Valid values:

  • true: enables the feature. Only enterprise SSD disks (excluding standard SSD) support this feature.

  • false: disables the feature. A standard snapshot is created.

Default value: false.

Note

This parameter is deprecated. Standard snapshots for enterprise SSD disks (excluding standard SSD) have been upgraded to active by default. No additional configuration is required, and no extra costs are incurred.

false

InstantAccessRetentionDays

integer

No

Settings for the retention period of the snapshot instant access feature. The snapshot is subject to automatic release when the retention period expires. This parameter takes effect only when InstantAccess is set to true. Unit: days. Valid values: 1 to 65535.

Default value: the value of the RetentionDays parameter.

Note

This parameter is deprecated. Standard snapshots for enterprise SSD disks (excluding standard SSD) have been upgraded to active by default. No additional configuration is required, and no extra costs are incurred.

1

Tag

array<object>

No

The list of tags.

object

No

The list of tags.

Key

string

No

The key of tag N of the snapshot. Valid values of N: 1 to 20. If this parameter is specified, it cannot be an empty string. The tag key can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://.

TestKey

Value

string

No

The value of tag N of the snapshot. Valid values of N: 1 to 20. If this parameter is specified, it can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://.

TestValue

key

string

No

The key of the tag.

Note

To improve compatibility, we recommend that you use the Tag.N.Key parameter.

null

value

string

No

The value of the tag.

Note

To improve compatibility, we recommend that you use the Tag.N.Value parameter.

null

StorageLocationArn

string

No

Note

This parameter is not available.

null

Response elements

Element

Type

Description

Example

object

RequestId

string

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

SnapshotId

string

The ID of the snapshot.

s-bp17441ohwka0yuh****

Examples

Success response

JSON format

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "SnapshotId": "s-bp17441ohwka0yuh****"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter.KMSKeyId.NotFound The specified KMSKeyId does not exist. Please verify that the key ID is correct and that the key resides in the current region.
400 InvalidSnapshotName.Malformed The specified SnapshotName is malformed.
400 IncorrectInstanceStatus The current status of the resource does not support this operation. The resource is in a state that does not support the current operation.
400 DiskCategory.OperationNotSupported The type of the specified disk does not support creating a snapshot. The operation is not supported by the current disk category.
400 Duplicate.TagKey The parameter Tag.N.Key contains duplicate values. Please remove the duplicate tag keys and try again.
400 InvalidTagKey.Malformed The specified Tag.n.Key is not valid. The specified Tag.N.Key parameter is invalid.
400 InvalidTagValue.Malformed The specified Tag.n.Value is not valid. The specified tag value is invalid.
400 InvalidRetentionDays.Malformed The specified RetentionDays is not valid. The specified RetentionDays parameter is invalid.
400 CreateSnapshot.Failed The process of creating snapshot is failed. Failed to create the snapshot.
400 InvalidOperation.StorageLocationMismatch The specified storageLocation does not match the storage location of the last snapshot for the disk. Ensure the storageLocation is consistent with previous snapshots.
500 InternalError The request processing has failed due to an internal error and you may retry later or contact support with the request ID.
403 Throttling Request was denied due to user flow control. The request is throttled.
403 IncorrectDiskStatus.CreatingSnapshot A previous snapshot creation is in process.
403 InstanceLockedForSecurity The disk attached instance is locked due to security.
403 IncorrectDiskStatus.NeverAttached The specified disk has never been attached to any instance.
403 QuotaExceed.Snapshot The snapshot quota exceeds.
403 IncorrectDiskStatus.NeverUsed The specified disk has never been used after creating.
403 CreateSnapshot.Failed The process of creating snapshot is failed.
403 DiskInArrears The specified operation is denied as your disk has expired.
403 DiskId.ValueNotSupported The specified parameter diskid is not supported. The specified EBS device category does not support the operation.
403 IncorrectDiskStatus The current disk status does not support this operation.
403 InvalidAccountStatus.NotEnoughBalance Your account does not have enough balance.
403 InvalidAccountStatus.SnapshotServiceUnavailable The snapshot service has not been activated. Please activate it and try again.
403 IncorrectInstanceStatus The current status of the resource does not support this operation.
403 IncorrectVolumeStatus The current volume status does not support this operation. The current state does not support this operation.
403 IdempotentParameterMismatch The specified clientToken is used. The specified client token is already in use.
403 IncorrectDiskStatus.Invalid The specified disk status is invalid. Restart the instance and try again.
403 IncorrectDiskType.NotSupport The specified device type is not supported. The specified disk type does not support the operation.
403 IncorrectDiskStatus.Transferring The specified device is transferring. You can retry after the process is finished.
403 InvalidParameter.KMSKeyId.CMKUnauthorized ECS tags must be added to the CMK. ECS tags must be added to the CMK.
403 InvalidParameter.KMSKeyId.CMKNotEnabled The CMK needs to be enabled.
403 InvalidParameter.KMSKeyId.KMSUnauthorized ECS service does not have permission to access your KMS key. Please verify that the specified KMS key has authorized the ECS service.
403 IdempotentProcessing The previous idempotent request(s) is still processing. A previous idempotent request is being processed. Try again later.
403 InvalidSnapshotCategory.Malformed The specified Category is not valid. The specified Category parameter is invalid.
403 InvalidAction.Unauthorized The specified action is not valid. The specified operation is invalid.
403 InvalidRegion.NotSupportSnapshotInstantAccessRegion The snapshot InstantAccess is not supported for this region.
403 InvalidCategoryAndInstantAccess.Malformed The snapshot Category and InstantAccess can't be used together.
403 DISK_HAS_CREATING_SNAPSHOT The operation cannot be performed while a snapshot is being created for the disk.
403 HibernationConfigured.InstanceOperationForbidden The operation is not permitted due to limit of the hibernation configured instance. The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled.
403 QuotaExceed.SnapshotQuota The quota is insufficient. Please contact your channel partner to increase the quota.
403 InvalidInstantAccessRetentionDays.Malformed The specified InstantAccessRetentionDays is not valid. The format of the specified InstantAccessRetentionDays parameter is invalid.
403 CloudBoxNotSupportSnapshotWithInstantAccess The specified disk in CloudBox does not support to create a snapshot with InstantAccess. Disks in CloudBox do not support creating snapshots with the instant access feature.
403 InvalidOperation.UnfinishedEncryptedSnapshotCopy This disk has unfinished encrypted copy snapshots in the target region. The cloud disk has unfinished encrypted snapshot copy tasks.
403 QuotaExceed.ConcurrentSnapshotQuota The number of snapshots being created for the disk %s has exceeded the concurrent quota (%s). Please wait for the previous snapshots to complete before trying again. The number of snapshots being created for this disk has exceeded the concurrent quota. Please wait for the previous snapshots to complete before trying again.
403 InvalidClientToken.Malformed The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length. The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length.
403 InvalidParameter.UnauthorizedStorageLocationArn The operation has failed due to lack of permission for the specified "StorageLocationArn". Please use a resource with appropriate permission for the operation. The current operation failed because the specified StorageLocationArn has insufficient permissions. Contact the administrator of the resource to obtain the operation permissions.
403 InvalidStorageLocationArn.Malformed The specified parameter StorageLocationArn is malformed.
403 InvalidStatus.ResourceGroup You cannot perform an operation on a resource group that is being created or deleted. Operation not allowed while resource group is being created or deleted.
403 OperationDenied.QuotaExceed The quota of tags on resource is beyond permitted range. The maximum number of tags on resource is exceeded.
403 Forbidden.InDebt The operation is not allowed because your account has an outstanding balance. Please settle the overdue payment and try again.
403 InvalidOperation.RegionUnsupported Creating snapshots is not supported in the specified region. Please use a region that supports the snapshot feature. the specified region does not support snapshot creation. Use a region that supports the snapshot function.
403 OperationDenied.KMSKeyUnauthorized The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation.
404 InvalidDiskId.NotFound The specified DiskId does not exist. Please verify the disk ID and the current region. The specified DiskId does not exist. Verify the disk ID and current region.
404 InvalidDescription.Malformed The specified parameter Description is not valid. Please ensure that the description is 2 to 256 characters long and does not start with "http://" or "https://" and try again. The specified Description parameter is invalid. Please ensure that the description is between 2 and 256 characters long, uses either English or Chinese characters, and does not begin with "http://" or "https://", then try again.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The specified instanceId is invalid.
404 InvalidVolumeId.NotFound The specified volume does not exist.
404 InvalidResourceGroup.NotFound The ResourceGroup provided does not exist in our records. The specified resource group does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.