Skip to content

Resize a pool

Change a pool's shared CPU, RAM and storage. Resume a paused pool before resizing it. The new size must fit the pool's Computers, ports and stored data. Use buy.plan or buy_rest to buy additional capacity, or release: true to release whole purchases freed by shrinking.

Parameters

#
poolstringRequired
Pool name or ID.
memorystring
New total RAM from existing capacity in multiples of 8 GiB, with 2 vCPUs and corresponding storage per unit.
unitsstring
New total size from 1 to 64 units of 2 vCPUs and 8 GiB of RAM. Use buy_rest to buy capacity beyond your unused units.
buyobject
Show 3 attributesHide attributes
planstring
Plan number from plan view. The entire plan is added to the pool on its server.
monthlyboolean
With buy.plan, pay monthly for new capacity (default).
hourlyboolean
With buy.plan, pay for new capacity from your wallet by the minute, with a minimum charge of one hour.
buy_reststring
Billing model for capacity needed beyond unused units. Give monthly or hourly.
monthsstring
Length of a new monthly purchase's prepaid term with buy.plan. Choose 1 (default) or 12.
offerstring
Offer code for new capacity bought for this resize.
releaseboolean
Release capacity freed by shrinking, where whole plans allow. Hourly billing ends immediately; monthly billing ends after the paid period.
dry_runboolean
Preview the resulting size, purchases and releases. Available with buy.plan or units, or when using release: true.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
Pool capacity and any purchases or releases.
Show 2 attributesHide attributes
alternative-1object
A pool's resulting or proposed capacity and purchase. Pending payment must complete before the pool is created or enlarged.
Show 16 attributesHide attributes
charged_centsinteger
Immediate charge, or the previewed charge, in cents. May be omitted.
checkout_urlstring
First monthly purchase's payment page. May be omitted.
dry_runboolean
True when no pool or purchase was made. May be omitted.
growsboolean
True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
idstring
Pool ID, when a pool has been created. May be omitted.
invoice_urlstring
Payment page for an additional purchase needing your action. May be omitted.
kindstring
Billing model. May be omitted.
memory_bytesinteger
Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
planinteger
Purchased plan number. May be omitted.
poolstringAlways present
Pool name.
price_microsinteger
Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
purchasestring
Capacity purchase made for this pool. May be omitted.
storage_bytesinteger
Resulting included storage, in bytes. May be omitted.
unknownboolean
Whether the payment response was lost. Read capacity view before retrying. May be omitted.
vcpusinteger
Resulting vCPU allocation. May be omitted.
wallet_microsinteger
Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
alternative-2object
The result or preview of changing a pool's units. Pending purchases add capacity once paid.
Show 15 attributesHide attributes
computersinteger
Number of Computers deleted with the pool. May be omitted.
deletedboolean
Whether this request deleted the pool. May be omitted.
dry_runboolean
Whether the result is a preview. May be omitted.
from_unitsintegerAlways present
Pool's units before this request.
growobject
How additional units are supplied. May be omitted.
Show 6 attributesHide attributes
boughtobjectAlways present
New capacity needed for the increase.
Show 4 attributesHide attributes
memory_bytesintegerAlways present
RAM allocation in bytes.
storage_bytesintegerAlways present
Included storage in bytes.
unitsintegerAlways present
Number of units.
vcpusintegerAlways present
vCPU allocation.
charged_centsinteger
Amount charged now, or previewed, in cents. May be omitted.
from_unusedobjectAlways present
Existing purchased capacity assigned to the increase.
Show 4 attributesHide attributes
memory_bytesintegerAlways present
RAM allocation in bytes.
storage_bytesintegerAlways present
Included storage in bytes.
unitsintegerAlways present
Number of units.
vcpusintegerAlways present
vCPU allocation.
kindstring
New purchases' billing model. May be omitted.
plansobject[]
Plans bought to supply that capacity. May be omitted.
Show 1 attributeHide attributes
itemsobject
A plan purchased or proposed for a pool.
Show 8 attributesHide attributes
charged_centsinteger
Amount charged now, or its preview, in cents. May be omitted.
checkout_urlstring
Checkout page when payment is required. May be omitted.
invoice_urlstring
Invoice page when payment needs your action. May be omitted.
planintegerAlways present
Plan number.
price_microsintegerAlways present
Price per billing period, in millionths of a dollar. The enclosing result specifies the billing model.
purchasestring
Capacity purchase ID. May be omitted.
unitsintegerAlways present
Capacity units supplied by the plan.
unknownboolean
Whether the payment outcome is uncertain. Read capacity before buying again. May be omitted.
price_microsintegerAlways present
New purchases' combined hourly or monthly price, in millionths of a dollar.
idstringAlways present
Pool ID.
memory_bytesintegerAlways present
Resulting RAM in bytes, once pending payments complete.
messagestring
Effects a deletion preview would have. May be omitted.
pendingboolean
True when purchased capacity still awaits payment. May be omitted.
poolstringAlways present
Pool name.
releaseobject
Purchase releases or reductions. May be omitted.
Show 7 attributesHide attributes
changesobject[] | nullAlways present
Each purchase released or reduced, with any individual error.
Show 1 attributeHide attributes
itemsobject
A purchase's release or reduction during a pool resize.
Show 10 attributesHide attributes
atstring (date-time)
When the release or reduction takes effect. May be omitted.
errorobject
Reason this purchase change failed. Other purchases can succeed independently. May be omitted.
Show 7 attributesHide attributes
actionobject
A suggested command addressing the problem. May be omitted.
kindstringAlways present
Error category. unknown means the effect is uncertain; reconcile before retrying.
messagestringAlways present
What happened and any action needed from you.
operation_idstring
Operation to read before repeating uncertain work. May be omitted.
request_idstring
Request ID identifying the change during reconciliation. May be omitted.
retry_afterinteger
Seconds before retrying a rate-limited request or a refused wait. May be omitted.
urlstring
Payment page for a payment-required response. May be omitted.
kindstringAlways present
Billing model.
planintegerAlways present
Plan before the change.
price_microsintegerAlways present
Previous hourly or monthly price, in millionths of a dollar.
purchasestringAlways present
Purchase ID.
refunded_centsinteger
Any immediate refund, in cents. May be omitted.
to_planinteger
Smaller plan after the change. Absent when the purchase is released entirely. May be omitted.
to_price_microsintegerAlways present
Resulting hourly or monthly price, in millionths of a dollar.
unitsintegerAlways present
Units this purchase change releases.
freed_unitsintegerAlways present
Units returned by the pool.
fromstring (date-time)
Time the final scheduled release stops being billed. May be omitted.
renewal_micros_afterintegerAlways present
Account's monthly renewal total after the release, in millionths of a dollar.
renewal_micros_beforeintegerAlways present
Account's monthly renewal total before the release, in millionths of a dollar.
stays_unused_unitsintegerAlways present
Returned units still billed because purchase sizes do not match the release.
unitsintegerAlways present
Returned units that stop being paid for.
request_idstringAlways present
Request ID for this pool resize.
storage_bytesintegerAlways present
Resulting included storage in bytes, once pending payments complete.
unitsintegerAlways present
Requested resulting units. Zero represents deletion.
vcpusintegerAlways present
Resulting vCPU allocation, or the proposed allocation in a preview.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create).
  • A key limited to a command list cannot run this command.
  • For retries, reuse the original Idempotency-Key and inputs.
  • Within capacity: Resize the pool within purchased capacity. Required: memory. Optional: release, organization.
  • Of units: Resize the pool to the requested number of units. Required: units. Optional: buy_rest, release, dry_run, organization.
  • Buy a plan: Buy a plan on the pool's server and add its capacity to the pool after payment. Required: buy. Optional: months, offer, dry_run, organization.