All Products
Search
Document Center

Elastic Compute Service:CreateSnapshot

Last Updated:Jul 14, 2026

Creates a snapshot for a disk.

Operation description

The local snapshot feature has been replaced by the snapshot instant access feature. Metric description is as follows:

  • If you used local snapshots before December 14, 2020, you can use the Category parameter as Normal.

  • If you did not use local snapshots before December 14, 2020, no additional configuration is required. New snapshots created for ESSD series disks (ESSD, ESSD AutoPL, ESSD Entry, and regional ESSD) are instantly active by default, and both manual snapshots and automatic snapshots are supported. The three snapshot instant access-related parameters InstantAccess, InstantAccessRetentionDays, and DisableInstantAccess in API operations no longer take effect. The DescribeSnapshots and DescribeSnapshotGroups API operations will include a new response parameter named Available to describe the active status of snapshots.

Before you begin:

  • Activate the snapshot feature. For more information, see Activate snapshots.

  • The disk must be in the In Use or Unattached state. Note the following items for different states:

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

    • If the disk is in the Unattached state, the disk must have been previously attached to an ECS instance. Snapshots cannot be created for disks that have never been attached to an ECS instance.

    • When a disk is used to create a dynamic extended volume or a RAID array, use a snapshot-consistent group and enable application-consistent snapshots to back up data. Snapshot-consistent groups ensure write order consistency and crash consistency for data written to multiple disks in a business system. 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 up to 10%, and read and write performance may be briefly affected.

  • If the snapshot has not been created, it cannot be used to create a custom image (CreateImage).

  • Incremental data generated by disk operations during snapshot creation is not backup 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, the snapshot creation is failed.

  • A disk for which a snapshot is being created does not support scale-out. Wait until the snapshot is created before you execute the scale-out operation.

  • You can create snapshots for disks in the Expired (Expired) state. If the disk reaches its expiration release time during snapshot creation, the disk is released and the snapshot in the Creating (Creating) state is also deleted.

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

  • In the following scenarios, you cannot create a snapshot for the specified disk:

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

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

    • When you query ECS instance information, if the returned data 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 disk ID.

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 and cannot start with http:// or https://. The name can contain Unicode characters under the letter category (including letters in English and Chinese), ASCII digits (0-9), colons (:), underscores (_), periods (.), and hyphens (-).

Note

The name cannot start with auto to avoid conflicts with the names of automatic snapshots.

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

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: null, 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 will be deprecated. Standard snapshots of enterprise SSDs have been upgraded to instant access by default. No additional configuration or fees are required. This applies to enterprise SSDs, ESSD AutoPL disks, ESSD Entry disks, and regional enterprise SSDs. Standard snapshots of standard SSDs are also active by default.

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 token, but make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to 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 SSDs support this feature.

  • false: shutdown. A standard snapshot is created.

Default value: false.

Note

This parameter is deprecated. Standard snapshots of enterprise SSDs have been upgraded to instant access by default. No additional configuration or fees are required. This applies to enterprise SSDs, ESSD AutoPL disks, ESSD Entry disks, and regional enterprise SSDs. Standard snapshots of standard SSDs are also active by default.

false

InstantAccessRetentionDays

integer

No

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

Default value: the same as the value of the RetentionDays parameter.

Note

This parameter is deprecated. Standard snapshots of enterprise SSDs have been upgraded to instant access by default. No additional configuration or fees are required. This applies to enterprise SSDs, ESSD AutoPL disks, ESSD Entry disks, and regional enterprise SSDs. Standard snapshots of standard SSDs are also active by default.

1

Tag

array<object>

No

The tags.

object

No

The tags.

key

string

No

The tag key of the snapshot.

Note

For compatibility purposes, use the Tag.N.Key parameter.

null

Key

string

No

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

TestKey

Value

string

No

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

TestValue

value

string

No

The tag value of the snapshot.

Note

For compatibility purposes, use the Tag.N.Value parameter.

null

StorageLocationArn

string

No

Note

This parameter is not publicly available.

null

Response elements

Element

Type

Description

Example

object

SnapshotId

string

The snapshot ID.

s-bp17441ohwka0yuh****

RequestId

string

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

Examples

Success response

JSON format

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

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidParameter.KMSKeyId.NotFound The specified KMSKeyId does not exist.
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 Tag.N.Key contain duplicate key. The specified tag key already exists. Tag keys must be unique.
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.
500 InternalError The request processing has failed due to some unknown error.
403 Throttling Request was denied due to user flow control. The request is throttled. Use the NextToken-based pagination method instead of the PageNumber-based pagination method.
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 Snapshot service has not been opened yet. The operation is not supported while the snapshot service is not activated.
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 of the Shared Block Storage device 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 specified InstantAccessRetentionDays parameter has an invalid format.
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.
404 InvalidDiskId.NotFound The specified DiskId does not exist. The specified disk does not exist. Check whether the disk ID is correct.
404 InvalidDescription.Malformed The specified description is malformed.
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.