DescribeReservedInstances

Updated at:

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

Example: Query all reserved instances purchased in the China (Hangzhou) region

"Region":"cn-hangzhou" // Set the region to China (Hangzhou).

Example: Query the details of the reserved instance whose ID is ecsri-bp129enntoynwwj5**** in the China (Hangzhou) region

"Region":"cn-hangzhou", // Set the region to China (Hangzhou).
"ReservedInstanceId":"ecsri-bp129enntoynwwj5****" // Set the reserved instance ID.

Example: Query reserved instances that can be applied to ecs.c5.2xlarge instances in the China (Hangzhou) region

"Region":"cn-hangzhou", // Set the region to China (Hangzhou).
"InstanceType":"ecs.c5.2xlarge" // Set the instance type.

Example: Query active regional reserved instances in the China (Hangzhou) region

"Region":"cn-hangzhou", // Set the region to China (Hangzhou).
"Scope":"Region", // Set the scope of the reserved instance.
"Status":["Active"] // Set the status to Active.

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:DescribeReservedInstances

get

ReservedInstance

acs:ecs:{#regionId}:{#accountId}:reservedinstance/*

ReservedInstance

acs:ecs:{#regionId}:{#accountId}:reservedinstance/{#reservedinstanceId}

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 acs: and cannot contain http:// or https://.

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:

  • financial: The account has overdue payments or the service has expired.

  • security: The instance is locked for security reasons.

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

  • Zone: zonal.

Region

OfferingType

string

No

The payment type of the reserved instance. Valid values:

  • No Upfront: no upfront.

  • Partial Upfront: partial upfront.

  • All Upfront: all upfront.

All Upfront

AllocationType

string

No

The allocation type. Valid values:

  • Normal: queries the reserved instances under the current account.

  • Shared: queries the reserved instances that are shared between the main account and linked accounts under the current account.

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:

  • Creating: The reserved instance is being created.

  • Active: The reserved instance is active.

  • Retired: The reserved instance is retired.

  • Updating: The attributes of the reserved instance are being modified.

  • Expired: The reserved instance has expired. A reserved instance becomes invalid immediately after it expires. This value is deprecated and will be removed in the future.

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: The reserved instance is allocated to other users.

  • beAllocated: The reserved instance is allocated by other users.

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:

  • Windows: Windows Server operating systems.

  • Linux: Linux and Unix-like operating systems.

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.