Skip to content

Delete a pool

Delete a pool and its Computers, disks and snapshots. Freed capacity can be allocated to another pool on the same server. Include release: true to end whole purchases that are freed by the deletion.

Parameters

#
poolstringRequired
Pool name or ID.
releaseboolean
Release the deleted pool's capacity where whole plans allow. Hourly billing ends immediately; monthly billing ends after the paid period.
dry_runboolean
Preview the Computers and files to delete and capacity to release.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
A pool deletion result and retained purchases, or a capacity release result.
Show 3 attributesHide attributes
alternative-1object
An accepted pool deletion and retained purchases.
Show 3 attributesHide attributes
billedobject[] | nullAlways present
Retained purchases that continue to be billed.
Show 1 attributeHide attributes
itemsobject
A capacity purchase and its payment status.
Show 15 attributesHide attributes
checkout_urlstring
Payment page for a pending purchase. May be omitted.
created_atstring (date-time)Always present
When the purchase was created.
idstringAlways present
Purchase ID used for changes or release.
kindstringAlways present
Billing model.
memory_bytesintegerAlways present
RAM included by this purchase, in bytes.
next_termsobject
Scheduled replacement terms. May be omitted.
Show 8 attributesHide attributes
amount_microsintegerAlways present
Price per billing period before discounts or a trial, in millionths of the currency.
currencystringAlways present
Currency of the price.
egress_gbintegerAlways present
Included monthly internet egress in decimal gigabytes.
modelstringAlways present
Hourly or monthly billing. Values: "hourly", "monthly".
planintegerAlways present
Plan number.
rate_cardobjectAlways present
Rates for usage beyond included allowances.
Show 2 attributesHide attributes
egress_micros_per_gbintegerAlways present
Internet egress overage price per decimal gigabyte, in millionths of a dollar.
hourly_minimum_minutesintegerAlways present
Minimum billed duration of an hourly purchase, in minutes.
storage_gbintegerAlways present
Included storage in decimal gigabytes.
unitsintegerAlways present
Number of capacity units purchased.
next_terms_atstring (date-time)
When replacement terms take effect. Monthly changes apply at renewal. May be omitted.
pays_microsinteger
Current price per hour or month according to kind, in millionths of a dollar. May be omitted.
planintegerAlways present
Purchased plan number.
poolsstring[] | nullAlways present
Pools that use capacity in this purchase's placement.
regionstring
Purchase's region. May be omitted.
statestringAlways present
active capacity is available. pending awaits its first monthly payment. out_of_funds, capped (stopped at the spending cap) and unpaid purchases have lapsed and contribute no capacity.
storage_bytesintegerAlways present
Storage included by this purchase, in bytes.
termsobject
Price and allowances agreed to for this purchase. May be omitted.
Show 8 attributesHide attributes
amount_microsintegerAlways present
Price per billing period before discounts or a trial, in millionths of the currency.
currencystringAlways present
Currency of the price.
egress_gbintegerAlways present
Included monthly internet egress in decimal gigabytes.
modelstringAlways present
Hourly or monthly billing. Values: "hourly", "monthly".
planintegerAlways present
Plan number.
rate_cardobjectAlways present
Rates for usage beyond included allowances.
Show 2 attributesHide attributes
egress_micros_per_gbintegerAlways present
Internet egress overage price per decimal gigabyte, in millionths of a dollar.
hourly_minimum_minutesintegerAlways present
Minimum billed duration of an hourly purchase, in minutes.
storage_gbintegerAlways present
Included storage in decimal gigabytes.
unitsintegerAlways present
Number of capacity units purchased.
vcpusintegerAlways present
vCPUs included by this purchase.
computersintegerAlways present
Number of Computers removed with the pool.
poolstringAlways present
Deleted pool's name.
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.
alternative-3object
A preview of the requested change.
Show 3 attributesHide attributes
changesstring[]
Proposed effects and losses. May be omitted.
dry_runbooleanAlways present
True for a preview; no changes are made.
messagestringAlways present
What the request would do.

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.