DescribeCapacityReservations
Queries the details of one or more capacity reservations, such as the status, effective and expiration time, private pool mode, and number of used instances.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:DescribeCapacityReservations |
get |
*CapacityReservation
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| RegionId |
string |
Yes |
The region ID of the capacity reservation. You can call the DescribeRegions operation to query the most recent region list. |
cn-hangzhou |
| ResourceGroupId |
string |
No |
The resource group ID. When you use this parameter to filter resources, the resource count cannot exceed 1,000. Note
Default resource group filtering is not supported. |
rg-bp67acfmxazb4p**** |
| Tag |
array<object> |
No |
The tags bound to the capacity reservation. |
|
|
object |
No |
The tag key-value pair. |
||
| Key |
string |
No |
The tag key. N specifies that you can set multiple tag keys for filtering. Valid values of N: 1 to 20. When you use a single tag to filter resources, the resource count returned cannot exceed 1,000. When you use multiple tags to filter resources, the resource count of resources that attach to all the specified tags cannot exceed 1,000. If the resource count exceeds 1,000, call the ListTagResources operation to query the resources. |
TestKey |
| Value |
string |
No |
The tag value. N specifies that you can configure multiple tag values for filtering. Valid values of N: 1 to 20. |
TestValue |
| MaxResults |
integer |
No |
The number of entries per page for a paged query. Maximum value: 100. Default value: 10. |
10 |
| NextToken |
string |
No |
The pagination token for the capacity reservation query. You can obtain the token from the response of the previous request. |
caeba0bbb2be03f84eb48b699f0a4883 |
| PrivatePoolOptions.Ids |
string |
No |
The IDs of the capacity reservations. The value can be a JSON array that consists of up to 100 capacity reservation IDs. Separate multiple IDs with commas (,). |
["crp-bp1gubrkqutenqdd****", "crp-bp67acfmxazb5****"] |
| Platform |
string |
No |
The operating system of the instance. Valid values:
Default value: all. |
linux |
| InstanceType |
string |
No |
The instance type. You can use this parameter to query only active capacity reservations. To query released capacity reservations, you can only use the PrivatePoolOptions.Ids parameter. |
ecs.c6.large |
| ZoneId |
string |
No |
The zone ID of the capacity reservation. |
cn-hangzhou-h |
| InstanceChargeType |
string |
No |
The billing method of the instance. Valid values:
Default value: PostPaid. |
PostPaid |
| Status |
string |
No |
The status of the capacity reservation. Valid values:
If you do not specify this parameter, capacity reservations in all statuses except Pending and Released are queried. |
Active |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| NextToken |
string |
The pagination token for the next query. |
caeba0bbb2be03f84eb48b699f0a**** |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3**** |
| TotalCount |
integer |
The total number of entries that meet the query conditions. |
1 |
| MaxResults |
integer |
The number of entries returned per page. |
10 |
| CapacityReservationSet |
object |
||
| CapacityReservationItem |
array<object> |
The collection of capacity reservation details. |
|
|
array<object> |
The capacity reservation details. |
||
| Status |
string |
The status of the capacity reservation. Valid values:
|
Active |
| TimeSlot |
string |
Note
This parameter is in invitational preview and is not available for public use. |
null |
| PrivatePoolOptionsMatchCriteria |
string |
The type of the private pool generated after the capacity reservation takes effect. Valid values:
|
Open |
| PrivatePoolOptionsId |
string |
The ID of the capacity reservation. |
crp-bp1gubrkqutenqdd**** |
| PrivatePoolOptionsName |
string |
The service name of the capacity reservation. |
crpTestName |
| RegionId |
string |
The region ID of the capacity reservation. |
cn-hangzhou |
| InstanceChargeType |
string |
The billing method of the instance in the capacity reservation. Valid values:
|
PostPaid |
| EndTime |
string |
The expiration time of the capacity reservation. The time follows the ISO 8601 standard and is displayed in UTC. |
2021-02-19T03:02Z |
| StartTime |
string |
The effective period of the capacity reservation. The format is ISO 8601, and the time zone is UTC. |
2021-02-19T02:01Z |
| Description |
string |
The description of the capacity reservation. |
This is description. |
| EndTimeType |
string |
The expiration method of the capacity reservation. Valid values:
|
Unlimited |
| ResourceGroupId |
string |
The ID of the resource group to which the capacity reservation belongs. |
rg-bp67acfmxazb4p**** |
| Platform |
string |
The operating system of the matched instance. Valid values:
|
linux |
| AllocatedResources |
object |
||
| AllocatedResource |
array<object> |
The list of resource allocation details. |
|
|
array<object> |
The resource allocation details. |
||
| UsedAmount |
integer |
The number of used instances. |
2 |
| TotalAmount |
integer |
The total number of instances to be reserved for the instance type. |
2 |
| AvailableAmount |
integer |
The number of available instances. |
2 |
| FailedAmount |
integer |
The failed capacity. |
1 |
| LockedAmount |
integer |
The locked capacity. |
1 |
| zoneId |
string |
The zone ID. |
cn-hangzhou-h |
| InstanceType |
string |
The instance type. |
ecs.c6.large |
| CapacityReservationUsages |
object |
||
| CapacityReservationUsage |
array<object> |
The list of used instance details. |
|
|
object |
The used instance details. |
||
| AccountId |
string |
The Alibaba Cloud account ID. |
105909559088**** |
| ServiceName |
string |
The Alibaba Cloud service name. |
maxcompute.aliyuncs.com |
| UsedAmount |
integer |
The number of instances used by the Alibaba Cloud account or service. |
20 |
| Tags |
object |
||
| Tag |
array<object> |
The list of tag key-value pairs bound to the capacity reservation. |
|
|
object |
The tag key-value pair bound to the capacity reservation. |
||
| TagValue |
string |
The tag value. |
TestValue |
| TagKey |
string |
The tag key. |
TestKey |
| StartTimeType |
string |
The effective method of the capacity reservation. Valid values:
|
Now |
| SavingPlanId |
string |
The ID of the savings plan associated with the capacity reservation. |
spn-c29b5e18pJMT**** |
| ReservedInstanceId |
string |
The ID of the reserved instance associated with the capacity reservation. |
ri-bpzhex2ulpzf53**** |
| CapacityReservationOwnerId |
string |
The ID of the owner of the capacity reservation. |
100************7 |
| DeliveryTime |
string |
The delivery time. The time follows the ISO 8601 standard and is displayed in UTC. |
2026-01-01T00:00:00Z |
| UnlockedTime |
string |
The unlock time. The time follows the ISO 8601 standard and is displayed in UTC. |
2026-01-02T00:00:00Z |
Examples
Success response
JSON format
{
"NextToken": "caeba0bbb2be03f84eb48b699f0a****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
"TotalCount": 1,
"MaxResults": 10,
"CapacityReservationSet": {
"CapacityReservationItem": [
{
"Status": "Active",
"TimeSlot": "null",
"PrivatePoolOptionsMatchCriteria": "Open",
"PrivatePoolOptionsId": "crp-bp1gubrkqutenqdd****",
"PrivatePoolOptionsName": "crpTestName",
"RegionId": "cn-hangzhou",
"InstanceChargeType": "PostPaid",
"EndTime": "2021-02-19T03:02Z",
"StartTime": "2021-02-19T02:01Z",
"Description": "This is description.",
"EndTimeType": "Unlimited",
"ResourceGroupId": "rg-bp67acfmxazb4p****",
"Platform": "linux",
"AllocatedResources": {
"AllocatedResource": [
{
"UsedAmount": 2,
"TotalAmount": 2,
"AvailableAmount": 2,
"FailedAmount": 1,
"LockedAmount": 1,
"zoneId": "cn-hangzhou-h",
"InstanceType": "ecs.c6.large",
"CapacityReservationUsages": {
"CapacityReservationUsage": [
{
"AccountId": "105909559088****",
"ServiceName": "maxcompute.aliyuncs.com",
"UsedAmount": 20
}
]
}
}
]
},
"Tags": {
"Tag": [
{
"TagValue": "TestValue",
"TagKey": "TestKey"
}
]
},
"StartTimeType": "Now",
"SavingPlanId": "spn-c29b5e18pJMT****",
"ReservedInstanceId": "ri-bpzhex2ulpzf53****",
"CapacityReservationOwnerId": "100************7\n",
"DeliveryTime": "2026-01-01T00:00:00Z",
"UnlockedTime": "2026-01-02T00:00:00Z"
}
]
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | MissingParameter.RegionId | The specified RegionId should not be null. | The RegionId parameter is required. |
| 400 | InvalidParameter.Name | The specified PrivatePoolOptions.Name is invalid. | |
| 400 | InvalidParameter.PrivatePoolOptions.Ids | The specified PrivatePoolOptions.Ids is invalid. | |
| 400 | DedicatedHostNotSupported | DedicatedHost is not supported for PrivatePool. | The private pool does not support dedicated hosts. |
| 400 | SpotNotSupported | Spot is not supported for PrivatePool. | The private pool does not support spot instances. |
| 400 | ClassicNetworkNotSupported | Classic network is not supported for PrivatePool. | The private pool does not support instances in the classic network. |
| 400 | Invalid.InstanceId | Instance does not exist. | The specified instance does not exist. |
| 400 | Invalid.PrivatePoolOptions.MatchCriteria | Target mode does not support this operation. | The operation is not supported while the PrivatePoolOptions.MatchCriteria parameter is set to Target. |
| 400 | MissingParameter.PrivatePoolOptions.Id | The specified PrivatePoolOptions.Id should not be null. | The PrivatePoolOptions.Id parameter is required. |
| 400 | Invalid.PrivatePoolOptions.Id | The PrivatePool does not exist. | The private pool does not exist. |
| 400 | Invalid.InstanceType | The InstanceType does not match the PrivatePool. | The instance type and the private pool do not match. |
| 400 | Invalid.InstanceChargeType | The InstanceChargeType does not match the PrivatePool. | The instance billing method and the private pool do not match. |
| 400 | Invalid.ZoneId | The ZoneId does not match the PrivatePool. | The zone and the private pool do not match. |
| 400 | Invalid.PrivatePoolOptions.status | The PrivatePool has been used up. | The resource is exhausted. |
| 400 | InvalidPlatform.ValueNotSupported | The Platform does not match the PrivatePool. | The specified Platform parameter does not match the private pool. |
| 400 | InvalidAliUid | The PrivatePool does not belong to the user of the Instance. | The specified private pool does not belong to the user who attempted to create the instance. |
| 400 | MissingParameter.PackageType | The specified parameter "PackageType" can not be empty. | The specified PackageType parameter cannot be empty. |
| 400 | MissingParameter.PrivatePoolOptions.Ids | The specified parameter "PrivatePoolOptions.Ids" can not be empty. | Specifies that the parameter "PrivatePoolOptions.ids" cannot be empty. |
| 400 | MissingParameter.InstanceCpuCoreCount | The specified parameter "InstanceCpuCoreCount" can not be empty. | The specified parameter 'InstanceCpuCocount' cannot be empty. |
| 400 | MissingParameter.InstanceAmount | The specified parameter "InstanceAmount" can not be empty. | The specified parameter InstanceAmount cannot be empty. |
| 400 | MissingParameter.InstanceCpuCoreCountOrInstanceAmount | The specified parameter "InstanceCpuCoreCount" and "InstanceAmount" must not be empty at the same time. | The specified parameter InstanceCpuCoreCount and InstanceAmount cannot be both empty. |
| 400 | Invalid.TooManyPrivatePoolOptions.Ids | Too many PrivatePoolOptions.Ids in this request. | The number of specified private pool IDs exceeds the upper limit. |
| 400 | Invalid.TooManyZoneIds | Too many ZoneIds in the request. | The number of specified zone IDs exceeds the upper limit. |
| 400 | Invalid.TooManyInstanceTypes | Too many InstanceTypes in the request. | The number of specified instance types exceeds the upper limit. |
| 400 | Invalid.TooManyUnpaidPrivatePool | Too many PrivatePools create but still unpaid. | Multiple private pools are created but not paid. |
| 400 | Invalid.InstanceCpuCoreCountOrInstanceAmount | Both InstanceCpuCoreCount and InstanceAmount are provided. | The InstanceCpuCoreCount and InstanceAmount parameters cannot be both specified. |
| 400 | Invalid.PrivatePoolOptions.Ids | The specified parameter "PrivatePoolOptions.Ids" exist invalid element Id. | The specified private pool ID does not exist. |
| 400 | Invalid.PackageType | The specified parameter "PackageType" is invalid. | The specified parameter PackageType is invalid. |
| 400 | Invalid.PrivatePool.Purchase | The PrivatePool has already paid. | The private pool is already paid. |
| 400 | Invalid.AssuranceTimes.NotSupported | The value of AssuranceTimes is not supported. | The specified AssuranceTimes parameter is invalid. |
| 400 | RepeatStartPrivatePool | PrivatePool has already been started. | The private pool is already started. |
| 400 | InvalidParameter.RegionId | The specified RegionId is not exist. | |
| 400 | InvalidPermission.ResourceShareAssocoated | The current resource is associated to a shared relationship and cannot be released. | The current resource is bound to a sharing relationship and cannot be released. |
| 500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | An internal error has occurred. Try again later. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.