DescribeReservedInstances
Queries the details of reserved instances that you have purchased in a specified region. You can filter the results by tags, reserved instance attributes, and other parameters.
Operation description
Scenarios
Query all reserved instances in a specified region.
Query the details of a reserved instance by its ID or name.
Filter reserved instances by instance type or instance family.
Filter reserved instances by scope or status.
Request examples
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:DescribeReservedInstances |
get |
ReservedInstance
ReservedInstance
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| RegionId |
string |
Yes |
The region ID of the reserved instance. You can call the DescribeRegions operation to query the most recent region list. |
cn-hangzhou |
| PageNumber |
integer |
No |
The page number of the reserved instance list. Pages start from 1. Default value: 1. |
1 |
| PageSize |
integer |
No |
The number of entries per page for a paging query. Maximum value: 100. Default value: 10. |
50 |
| Tag |
array<object> |
No |
The tags. Array length: 1 to 20. |
|
|
object |
No |
The tag. |
||
| Key |
string |
No |
The tag key of the reserved instance. The tag key cannot be an empty string and can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://. Note
If you use a single tag to filter resources, the resource count returned cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of resources that have multiple tags attached 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 of the reserved instance. The tag value cannot be an empty string and can be up to 128 characters in length. It cannot start with |
TestValue |
| ZoneId |
string |
No |
The zone ID of the instance. This parameter is required and takes effect only when Scope is set to Zone. You can call the DescribeZones operation to query the zone list. |
cn-hangzhou-z |
| ReservedInstanceName |
string |
No |
The name of the reserved instance. Note
Exact match is used. Fuzzy match is not supported. |
testReservedInstanceName |
| LockReason |
string |
No |
The lock type. Valid values:
|
security |
| InstanceType |
string |
No |
The instance type that matches the reserved instance. For more information, see Instance families. Note
This is the instance type selected when you purchase the reserved instance. When the reserved instance is applied, a regional reserved instance can be applied to different instance types within the same instance family based on the equivalence calculation. |
ecs.g5.large |
| InstanceTypeFamily |
string |
No |
The instance family that matches the reserved instance. For more information, see Instance families. |
ecs.g5 |
| Scope |
string |
No |
The scope of the reserved instance. Valid values:
|
Region |
| OfferingType |
string |
No |
The payment type of the reserved instance. Valid values:
|
All Upfront |
| AllocationType |
string |
No |
The allocation type. Valid values:
Default value: Normal. |
Normal |
| ReservedInstanceId |
array |
No |
The reserved instance IDs. Array length: 1 to 100. |
ri-bpzhex2ulpzf53**** |
|
string |
No |
The reserved instance ID. |
ri-bpzhex2ulpzf53**** |
|
| Status |
array |
No |
The statuses of the reserved instances. |
Active |
|
string |
No |
The status of the reserved instance. Valid values:
|
Active |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| PageSize |
integer |
The number of entries per page. |
1 |
| RequestId |
string |
The request ID. |
E572643C-6A29-49D6-9D4E-6CFA4E063A3E |
| PageNumber |
integer |
The page number of the reserved instance list. |
1 |
| TotalCount |
integer |
The total number of reserved instances. |
1 |
| ReservedInstances |
object |
||
| ReservedInstance |
array<object> |
The details of the reserved instances. |
|
|
array<object> |
The details of the reserved instance. |
||
| Status |
string |
The status. |
Active |
| CreationTime |
string |
The creation time. The time follows the ISO 8601 standard and is displayed in UTC. |
2018-12-10T12:07Z |
| ReservedInstanceName |
string |
The name. |
riZbpzhex2ulpzf53**** |
| ReservedInstanceId |
string |
The reserved instance ID. |
ri-bpzhex2ulpzf53**** |
| InstanceType |
string |
The instance type of the matched pay-as-you-go instance. |
ecs.g5.large |
| InstanceAmount |
integer |
The number of pay-as-you-go instances of the same instance type that can be matched. |
10 |
| RegionId |
string |
The region ID. |
cn-hangzhou |
| OfferingType |
string |
The payment type. |
All Upfront |
| StartTime |
string |
The effective period. The format is ISO 8601, and the time zone is UTC. |
2018-12-10T12:00Z |
| Description |
string |
The description. |
testDescription |
| AllocationStatus |
string |
The allocation status of the reserved instance. This parameter is returned only when AllocationType is set to Shared. Valid values:
|
allocated |
| ExpiredTime |
string |
The expiration time. The time follows the ISO 8601 standard and is displayed in UTC. |
2019-12-10T12:07Z |
| ResourceGroupId |
string |
The resource group. |
EcsDocTest |
| ZoneId |
string |
The zone ID. |
cn-hangzhou-z |
| Platform |
string |
The operating system type of the image used by the instance. Valid values:
|
Linux |
| Scope |
string |
The scope. |
region |
| OperationLocks |
object |
||
| OperationLock |
array<object> |
Indicates whether the instance is locked. |
|
|
object |
Indicates whether the instance is locked. |
||
| LockReason |
string |
The lock reason. |
security |
| Tags |
object |
||
| Tag |
array<object> |
The tags of the reserved instance. |
|
|
object |
The tag of the reserved instance. |
||
| TagValue |
string |
The tag value of the reserved instance. |
TestValue |
| TagKey |
string |
The tag key of the reserved instance. |
TestKey |
Examples
Success response
JSON format
{
"PageSize": 1,
"RequestId": "E572643C-6A29-49D6-9D4E-6CFA4E063A3E",
"PageNumber": 1,
"TotalCount": 1,
"ReservedInstances": {
"ReservedInstance": [
{
"Status": "Active",
"CreationTime": "2018-12-10T12:07Z",
"ReservedInstanceName": "riZbpzhex2ulpzf53****",
"ReservedInstanceId": "ri-bpzhex2ulpzf53****",
"InstanceType": "ecs.g5.large",
"InstanceAmount": 10,
"RegionId": "cn-hangzhou",
"OfferingType": "All Upfront",
"StartTime": "2018-12-10T12:00Z",
"Description": "testDescription",
"AllocationStatus": "allocated",
"ExpiredTime": "2019-12-10T12:07Z",
"ResourceGroupId": "EcsDocTest",
"ZoneId": "cn-hangzhou-z",
"Platform": "Linux",
"Scope": "region",
"OperationLocks": {
"OperationLock": [
{
"LockReason": "security"
}
]
},
"Tags": {
"Tag": [
{
"TagValue": "TestValue",
"TagKey": "TestKey"
}
]
}
}
]
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | MissingParamter.RegionId | The regionId should not be null. | The RegionId parameter is required. |
| 400 | InvalidRegion.NotFound | The specified parameter RegionId is not valid. | The specified RegionId parameter is invalid. |
| 400 | InvalidZone.NotFound | The specified parameter ZoneId is not valid. | The specified ZoneId parameter is invalid. |
| 400 | InvalidReservedInstanceOfferingType.ValueNotSupported | the OfferingType is not supported | |
| 400 | InvalidReservedInstanceOfferingClass.ValueNotSupported | the OfferingClass is not supported | |
| 400 | OperationDenied | The specified InstanceType or Zone is not authorized for current user. | |
| 400 | InvalidEndTime.ValueNotSupported | The specified endTime is out of the permitted range. | The specified end time is invalid. |
| 400 | InvalidReservedInstanceLockReason.ValueNotSupported | The specified LockReason is not supported. | |
| 400 | InvalidReservedInstanceStatus.ValueNotSupported | The specified Status is not supported. | |
| 400 | InvalidAllocationType.ValueNotSupported | The specified AllocationType is not supported. | The specified AllocationType parameter is invalid. |
| 403 | RAM.ApiNotSupported | This call is not supported from ram accessing. | RAM users are not authorized to perform this operation. |
| 404 | InvalidRegionId.NotFound | The specified RegionId does not exist in our records. | The specified RegionId parameter does not exist. Check whether the service is available in the specified region. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.