All Products
Search
Document Center

Auto Scaling:RemoveInstances

Last Updated:Oct 27, 2026

If the current scaling group is in the enable state and no scaling activity is in the execute state in the scaling group, you can invoke the RemoveInstances API operation to delete one or more unneeded instances from a scaling group.

Operation description

Operation description

  • Before you invoke this operation, make sure that the following conditions are met:

    • The scaling group is in the enable (Active) state.

    • No scaling activity is in the execute state in the scaling group.

When no scaling activity is in the execute state in the scaling group, this operation bypasses the cooldown time (DefaultCooldown) and will directly execute.

  • If an ECS instance is created through automatic creation by Auto Scaling, or was manually added and managed by the scaling group, the ECS instance will trigger the economical mode or be released when you delete the ECS instance from the scaling group.

  • If an ECS instance was manually added and is not managed by the scaling group, the ECS instance is not stopped or released when you delete the ECS instance from the scaling group.

  • If the number of instances in the scaling group (TotalCapacity) minus the number of instances specified in this operation is less than the minimum number of instances (MinSize) in the scaling group, the invocation failed.

A successful response to the invocation of this operation only indicates that the Auto Scaling service accepted the invocation request of this operation and the scaling activity can execute. It does not mean that the scaling activity will execute successfully. You must check the execute status of the scaling activity by using the returned ScalingActivityId.

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

ess:DetachInstances

update

*ScalingGroup

acs:ess:{#regionId}:{#accountId}:scalinggroup/{#ScalingGroupId}

None None

Request parameters

Parameter

Type

Required

Description

Example

ScalingGroupId

string

Yes

The ID of the scaling group.

asg-bp18p2yfxow2dloq****

RemovePolicy

string

No

Specifies the action for the removed ECS instances. Valid values:

  • recycle: The ECS instances enter the economical mode.

    Note

    This value takes effect only when ScalingPolicy is set to recycle.

  • release: The ECS instances are released.

    The ScalingPolicy parameter of CreateScalingGroup specifies the reclaim mode of the scaling group, but the specific action when an instance is removed is determined by the RemovePolicy parameter of RemoveInstances. Examples:

    • If ScalingPolicy is set to recycle and RemovePolicy is set to recycle, the ECS instances enter the economical mode.

    • If ScalingPolicy is set to recycle and RemovePolicy is set to release, the ECS instances are released.

    • If ScalingPolicy is set to release and RemovePolicy is set to recycle, the ECS instances are released.

    • If ScalingPolicy is set to release and RemovePolicy is set to release, the ECS instances are released.

Default value: release.

release

DecreaseDesiredCapacity

boolean

No

Specifies whether to modify the expected number of instances. Valid values:

  • true: After the ECS instances are removed from the scaling group, the expected number of instances is decreased by the number of removed instances.

  • false: After the ECS instances are removed from the scaling group, the expected number of instances remains unchanged.

Default value: true.

true

IgnoreInvalidInstance

boolean

No

Specifies whether to ignore invalid instances when you delete a batch of instances from the scaling group. Valid values:

  • true: Invalid instances are ignored when you delete a batch of instances from the scaling group.

    If invalid instances exist in the batch (for example, the instance status is Adding) and you successfully delete the valid instances, the execute status of the scaling activity is displayed as Warning. You can view the invalid instances in the scaling activity details.

  • false: Invalid instances are not ignored when you delete a batch of instances from the scaling group.

    If invalid instances exist in the batch, an error is returned.

Default value: false.

false

InstanceId

array

Yes

The IDs of the ECS instances to be removed.

i-28wt4****

string

No

The ID of the ECS instance to be removed. Valid values of N: 1 to 20.

i-28wt4****

RegionId

string

No

The region ID of the scaling group.

cn-qingdao

ClientToken

string

No

Ensures the idempotence of the request.

You can generate a parameter value from your client to ensure that the value is unique across different requests. The value can only contain ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

123e4567-e89b-12d3-a456-42665544****

StopInstanceTimeout

integer

No

The timeout period for waiting for the ECS instances to be stopped during the scale-in process. Unit: seconds. Valid values: 30 to 240.

Note
  • By default, this parameter value is inherited from the scaling group. You can also reset it when calling RemoveInstances.

  • This parameter takes effect only in the scale-in process when RemovePolicy is set to release.

  • If this parameter is set, the system waits for a maximum of the StopInstanceTimeout period for the instances to be stopped. After the timeout period elapses, the scale-in process continues regardless of whether the instances are successfully stopped.

  • If this parameter is not set, the system waits for a long time for the instances to be stopped. The scale-in process continues only after the instances are successfully stopped. If the instances fail to be stopped, the scale-in process is rolled back and the scale-in fails.

60

LifecycleHookContext

object

No

The context information of the lifecycle hooks.

DisableLifecycleHook

boolean

No

Specifies whether to disable all lifecycle hooks for the scaling activity. Valid values:

  • true: Disables all lifecycle hooks.

  • false: Does not disable lifecycle hooks.

false

IgnoredLifecycleHookIds

array

No

The IDs of the lifecycle hooks to be disabled for the scaling activity.

string

No

The IDs of the lifecycle hooks to be disabled for the scaling activity.

ash-bp14zolna43z266bq***

LifecycleHookResult

string

No

Response elements

Element

Type

Description

Example

object

ScalingActivityId

string

The ID of the scaling activity.

asa-bp175o6f6ego3r2j****

RequestId

string

The ID of the request.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

IgnoredInstances

object

IgnoredInstance

array<object>

object

InstanceId

string

Code

string

Message

string

Examples

Success response

JSON format

{
  "ScalingActivityId": "asa-bp175o6f6ego3r2j****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "IgnoredInstances": {
    "IgnoredInstance": [
      {
        "InstanceId": "",
        "Code": "",
        "Message": ""
      }
    ]
  }
}

Error codes

HTTP status code

Error code

Error message

Description

500 InternalError The request processing has failed due to some unknown error, exception or failure.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.