All Products
Search
Document Center

Elastic Compute Service:CreateSnapshot

Last Updated:Apr 24, 2026

Create a snapshot of a cloud disk.

Operation description

The instant access feature for snapshots replaces the legacy local snapshot feature. The parameters are described as follows:

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

  • If you did not use local snapshots before December 14, 2020, no additional configuration is required. New snapshots that are created for ESSD cloud disks (ESSDs, ESSD AutoPL disks, ESSD Entry disks, and zone-redundant ESSDs) have the instant access feature enabled by default. This applies to both manual and automatic snapshots. The instant access-related parameters InstantAccess, InstantAccessRetentionDays, and DisableInstantAccess no longer take effect. The DescribeSnapshots and DescribeSnapshotGroups API operations return an Available parameter that indicates the snapshot's status.

Prerequisites:

  • The snapshot feature is enabled. For more information, see Enable the snapshot feature.

  • The cloud disk must be in the in-use or available state. Note the following points:

    • If the cloud disk is in the in-use state, the instance to which the disk is attached must be in the running or stopped state.

    • If the cloud disk is in the available state, you can create snapshots for it only if it has been previously attached to an ECS instance.

    • When you use cloud disks to create dynamic scalable volumes or RAID arrays, we recommend that you use snapshot consistency groups and enable application-consistent snapshots to back up data. A snapshot consistency group ensures the crash consistency and write-order consistency of data written across multiple cloud disks. For more information, see Create a snapshot consistency group and Create an application-consistent snapshot.

Keep the following in mind when creating a snapshot:

  • Create snapshots during off-peak hours. During snapshot creation, the I/O performance of the cloud disk decreases by less than 10% and read and write operations may temporarily slow down.

  • You cannot use a snapshot that is being created to create a custom image (CreateImage).

  • The snapshot does not back up incremental data generated on the cloud disk during the creation process.

  • If the cloud disk is attached to an ECS instance, do not change the state of the instance, such as stopping or restarting the instance, during snapshot creation. Otherwise, the snapshot creation will fail.

  • You cannot resize a cloud disk during snapshot creation. You can resize the cloud disk only after the snapshot is complete.

  • You can create a snapshot for a cloud disk that is in the expired (Expired) state. If the cloud disk is released due to expiration when the snapshot is being created, the snapshot in the creating (Creating) state is also deleted.

  • After a snapshot is created, you are charged for the snapshot based on its size. The fees are settled on a per-region basis. For more information, see Snapshots.

  • You cannot create a snapshot for a cloud disk in the following cases:

    • The number of manual snapshots of the cloud disk has reached the upper limit. For more information, see Limits.

    • The limit on the number of snapshots that can be created concurrently has been reached. For more information, see Limits.

    • When you query the information of an ECS instance, if the returned data contains {"OperationLocks": {"LockReason" : "security"}}, all operations on the instance 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.

d-bp1s5fnvk4gn2tws0****

SnapshotName

string

No

The snapshot name must be 2 to 128 characters long. It must start with a letter or a Chinese character and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).

Note

The name cannot start with http:// or https://. To avoid conflicts with auto snapshot names, the name cannot start with auto.

testSnapshotName

Description

string

No

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

This parameter is empty by default.

testDescription

RetentionDays

integer

No

The retention period of the snapshot, in days. Valid values: 1 to 65,536. The snapshot is automatically deleted when the retention period expires.

If this parameter is not specified, the snapshot is retained indefinitely.

30

Category

string

No

The type of the snapshot. Valid values:

  • Standard: a standard snapshot.

  • Flash: a Flash Snapshot.

Note

This parameter is deprecated. standard snapshots for ESSD cloud disks now include the Instant Access feature by default at no additional cost.

Standard

ClientToken

string

No

A client-generated token to ensure request idempotence. The token must be unique for each request. The ClientToken value must be an ASCII string of up to 64 characters. 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 Instant Access feature. Valid values:

  • true: Enables the Instant Access feature. This feature can be enabled only for snapshots of ESSD cloud disks.

  • false: Disables the Instant Access feature. A standard snapshot is created.

Default value: false.

Note

This parameter is deprecated. standard snapshots for ESSD cloud disks now include the Instant Access feature by default at no additional cost.

false

InstantAccessRetentionDays

integer

No

The retention period for the Instant Access feature, in days. The snapshot is automatically deleted when this retention period expires. This parameter takes effect only when InstantAccess is set to true. Valid values: 1 to 65,535.

Defaults to the value of RetentionDays.

Note

This parameter is deprecated. standard snapshots for ESSD cloud disks now include the Instant Access feature by default at no additional cost.

1

Tag

array<object>

No

The tags to add to the snapshot. You can add up to 20 tags.

object

No

A tag consisting of a key-value pair.

key

string

No

The key of the tag.

Note

This parameter is not recommended. For better compatibility, use the Key parameter instead.

null

Key

string

No

The key of the tag.

Note

This parameter is not recommended. For better compatibility, use the Key parameter instead.

TestKey

Value

string

No

The tag value. It can be an empty string, must be 128 characters or shorter, and cannot contain http:// or https://.

TestValue

value

string

No

The tag value. It can be an empty string, must be 128 characters or shorter, and cannot contain http:// or https://.

null

StorageLocationArn

string

No

Note

This parameter is not available for public use.

null

Response elements

Element

Type

Description

Example

object

The response body for a successful request.

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 wrongly formed. The format of the specified snapshot name is invalid.
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.
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.
403 IdempotentParameterMismatch The specified clientToken is used. The specified client token is already in use.
403 IncorrectDiskStatus.Invalid The specified disk status invalid, restart instance and try again. The state of the specified disk 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. The specified disk is being migrated. Wait until the migration is complete and try again.
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 have no right to access your KMS. ECS is not authorized to access your KMS resources.
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. The quota is insufficient. Contact your channel partner to request a quota increase.
403 InvalidInstantAccessRetentionDays.Malformed The specified InstantAccessRetentionDays is not valid.
403 CloudBoxNotSupportSnapshotWithInstantAccess The specified disk in CloudBox does not support to create a snapshot with InstantAccess.
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 wrongly formed. The format of the specified parameter StorageLocationArn is incorrect.
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 wrongly formed.
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.