Elastic Compute Service
Elastic Compute Service
Document
- Documentation
Elastic Compute ServiceElastic Compute ServiceAPI ReferenceInstancesPurchaseReservedInstances - Purchases Reserved Instances
Copy page
Download PDFInstances
PurchaseReservedInstances - Purchases Reserved Instances
Copy pageDownload PDFPurchaseReservedInstances - Purchases Reserved Instances
Debugging
API Explorer
You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.
Request parameters
The table below lists only the request parameters specific to this operation and some common parameters. For more information, refer to Common parameters.
Action string required Sample value: PurchaseReservedInstances
The action that you want to perform. Value: PurchaseReservedInstances.
Version string required Sample value: 2020-04-01
The version of the API. Valid value: 2020-04-01.
AutoRenew boolean Optional Sample value: true
Whether to automatically renew the RI after its expiration.
- true: Enable automatic renewal.
- false (default): Does not enable automatic renewal.
AutoRenewPeriod integer Optional Sample value: 1
The renewal length for each automatic renewal.
- When AutoRenew is set to True, this parameter is valid.
- When PeriodUnit is set to Month, valid values are 1, 2, 3, 6, and 12. Default value is 1.
ClientToken string Optional Sample value: 333456899ff****
The ClientToken is used to ensure the request idempotency. You can use the client to automatically generate a token, but you must make sure that the token is unique among different requests. This prevents repeated actions due to multiple client retries when the call of the API action times out or an internal server error occurs.
Value: Only ASCII characters are supported. The length is no more than 64 ASCII characters.
Description string Optional Sample value: testDescription
RI description. Default value: empty string.
- It must start with a letter or Chinese character.
- Only Chinese characters, letters, numbers, dots (.), spaces, underscores (_), hyphen (-), equal signs (=), English comma (,), Chinese comma (，), and Chinese period (。) are allowed.
- The length is limited to 255 characters.
EffectiveAt string Optional Sample value: 2025-03-29T17:00:00+08:00
The RSC effective time. This parameter defaults to empty string which indicates that RSC takes effect immediately after purchase.
If the specified effective time is not on the hour, RSC takes effect at the current hour of the specified time. For example, if the specified time is 2025-03-29T17:50:00+08:00, the actual effective time is 2025-03-29T17:00:00+08:00.
HpcClusterId string Optional Sample value: hpcCluster-1
When you purchase RIs for HPC-optimized instances, specify the HPC cluster ID.
tip
If you need to purchase RI for this type of instance, contact the account manager to apply.
InstanceCount integer Optional Sample value: 1
The number of Pay-as-you-go instances that can be deducted or reserved with RIs. Value: 1–100. When 0 is passed in or no parameter is passed in, the default number is 1.
For example, if you have a zonal RI for the ecs.ecs.g3i.large instance type and set the instance count to 2, this RI can match 2 pay-as-you-go instances of the same type at the same time.
InstanceTypeId string required Sample value: ecs.g3i.large
Instance type that can be deducted or reserved by RIs.
Period integer Optional Sample value: 12
Subscription duration of RIs (month)
- Values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 24, 36
- Default value: 1
PeriodUnit string Optional Sample value: Month
The unit of purchase duration of RI. Value: Month.
ProjectName string Optional Sample value: project_a
The associated project. Each instance can only belong to one project.
- Only letters, digits, underscores (_), hyphens (-), and dots (.) are allowed.
- The length is limited to 64 characters.
RegionId string Optional Sample value: cn-beijing
The ID of the region specified in RI.
tip
When Scope is set to RegionalRI, this parameter is required.
ReservedCapacity integer Optional Sample value: 1
The capacity that can be reserved by RSC per hour, measured in GiB/hour or TiB/hour.
Value range: 65535 GiB to 64 TiB
- The total capacity of the package is calculated as ReservedCapacity multiplied by the number of hours in the validity period. Meanwhile, the maximum amount that can be deducted each hour is ReservedCapacity * 2.
- When ReservedStorageCapacityName is empty, this parameter is optional and invalid.
- When ReservedStorageCapacityName is not empty, this parameter is required.
ReservedInstanceName string required Sample value: reserved-instance-test
Enter the RI name.
- Cannot start with a number, a hyphen (-), or an underscore (_).
- Can only contain Chinese characters, letters, digits, underscores "_" and hyphens "-"
- The length limit is 1 to 128 characters.
- Special characters are currently not supported.
ReservedStorageCapacityName string Optional Sample value: RSC01
Enter the RSC name.
- Cannot start with a number, a hyphen (-), or an underscore (_).
- Only Chinese, letters, numbers, underscores and hyphens are allowed.
- The length limit is 1 to 128 characters.
- Special characters are currently not supported.
tip
An empty parameter indicates no RSC is purchased.
RscAutoRenew boolean Optional Sample value: true
Whether to automatically renew the RSC after its expiration. Value:
- true: Enable automatic renewal
- false (default): Disable automatic renewal
RscAutoRenewPeriod integer Optional Sample value: 1
The renewal length for each automatic renewal of RSC.
- When RscAutoRenew is set to True, this parameter is valid.
- When PeriodUnit is set to Month, this parameter takes one of the values 1, 2, 3, 6, or 12. The default value is 1.
Scope string Optional Sample value: ZonalRI
RI type. Value:
- ZonalRI (default): zonal RI
- RegionalRI: regional RI. Regional RI is currently in Beta. If you need a trial, contact the account manager to apply.
Tags.N.Key string[] required Sample value: Tags.1.Key=k1&Tags.2.Key=k2
The tag key of the user tag.
- Parameter - N: specifies the serial number of the tag key. Valid range: 1–20.
- Separate multiple keys with ampersands (&).
Naming rules:
- It cannot start with volc: or sys: in any combination of uppercase and lowercase letters.
- Only language characters, digits, spaces, and English symbols of "_", ".", ":", "/", "=", "+", "-", and "@" are allowed.
- It must be 1 to 128 characters in length.
tip
Keys of the same resource must be unique.
Tags.N.Value string[] Optional Sample value: Tags.1.Value=v1&Tags.2.Value=v2
The value of the user tag.
- Parameter - N: specifies the serial number of the tag value. Valid range: 1–20.
- Separate multiple key values with ampersands (&).
Naming rules:
- Only language characters, digits, spaces, and English symbols of "_", ".", ":", "/", "=", "+", "-", and "@" are allowed.
- It must be 0 to 256 characters in length.
tip
To pass in this parameter, pass in Tags.N.Key first.
VolumeType string Optional Sample value: ESSD_PL0
The volume type. Valid values:
- ESSD_PL0: ESSD PL0
- ESSD_FlexPL: ESSD FlexPL
tip
- When ReservedStorageCapacityName is empty, this parameter is optional and invalid.
- When ReservedStorageCapacityName is not empty, this parameter is required.
ZoneId string Optional Sample value: cn-beijing-a
The ID of the availability zone specified in RI.
tip
When Scope is set to ZonalRI, this parameter is required.
Response parameters
Only the response parameters specific to this operation are listed below. For more information, refer to the response structure.
ReservedInstanceId string Sample value: ecsri-ycq8kgnlxrb5oxt0****
ID of RI.
ReservedStorageCapacityId string Sample value: ebsrsc-3tigy72q3u3vj0x2****
RSC ID.
Sample request
Sample response
Error codes
The table below lists the business-related error codes of the operation. For more information, refer to Common error codes.
Last updated: 2026.06.18 17:48:24
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
