# Delete a pool

URL: https://heaven.dev/docs/reference/pools/delete
Updated: 2026-11-21

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.

`POST /v1/pool/delete`

## Parameters

- `pool` (string, required): Pool name or ID.
- `release` (boolean): Release the deleted pool's capacity where whole plans allow. Hourly billing ends immediately; monthly billing ends after the paid period.
- `dry_run` (boolean): Preview the Computers and files to delete and capacity to release.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): A pool deletion result and retained purchases, or a capacity release result.
  - `alternative-1` (object): An accepted pool deletion and retained purchases.
    - `billed` (object[] | null, always present): Retained purchases that continue to be billed.
      - `items` (object): A capacity purchase and its payment status.
        - `checkout_url` (string): Payment page for a pending purchase. May be omitted.
        - `created_at` (string (date-time), always present): When the purchase was created.
        - `id` (string, always present): Purchase ID used for changes or release.
        - `kind` (string, always present): Billing model.
        - `memory_bytes` (integer, always present): RAM included by this purchase, in bytes.
        - `next_terms` (object): Scheduled replacement terms. May be omitted.
          - `amount_micros` (integer, always present): Price per billing period before discounts or a trial, in millionths of the currency.
          - `currency` (string, always present): Currency of the price.
          - `egress_gb` (integer, always present): Included monthly internet egress in decimal gigabytes.
          - `model` (string, always present): Hourly or monthly billing. Values: `"hourly"`, `"monthly"`.
          - `plan` (integer, always present): Plan number.
          - `rate_card` (object, always present): Rates for usage beyond included allowances.
            - `egress_micros_per_gb` (integer, always present): Internet egress overage price per decimal gigabyte, in millionths of a dollar.
            - `hourly_minimum_minutes` (integer, always present): Minimum billed duration of an hourly purchase, in minutes.
          - `storage_gb` (integer, always present): Included storage in decimal gigabytes.
          - `units` (integer, always present): Number of capacity units purchased.
        - `next_terms_at` (string (date-time)): When replacement terms take effect. Monthly changes apply at renewal. May be omitted.
        - `pays_micros` (integer): Current price per hour or month according to `kind`, in millionths of a dollar. May be omitted.
        - `plan` (integer, always present): Purchased plan number.
        - `pools` (string[] | null, always present): Pools that use capacity in this purchase's placement.
        - `region` (string): Purchase's region. May be omitted.
        - `state` (string, always 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_bytes` (integer, always present): Storage included by this purchase, in bytes.
        - `terms` (object): Price and allowances agreed to for this purchase. May be omitted.
          - `amount_micros` (integer, always present): Price per billing period before discounts or a trial, in millionths of the currency.
          - `currency` (string, always present): Currency of the price.
          - `egress_gb` (integer, always present): Included monthly internet egress in decimal gigabytes.
          - `model` (string, always present): Hourly or monthly billing. Values: `"hourly"`, `"monthly"`.
          - `plan` (integer, always present): Plan number.
          - `rate_card` (object, always present): Rates for usage beyond included allowances.
            - `egress_micros_per_gb` (integer, always present): Internet egress overage price per decimal gigabyte, in millionths of a dollar.
            - `hourly_minimum_minutes` (integer, always present): Minimum billed duration of an hourly purchase, in minutes.
          - `storage_gb` (integer, always present): Included storage in decimal gigabytes.
          - `units` (integer, always present): Number of capacity units purchased.
        - `vcpus` (integer, always present): vCPUs included by this purchase.
    - `computers` (integer, always present): Number of Computers removed with the pool.
    - `pool` (string, always present): Deleted pool's name.
  - `alternative-2` (object): The result or preview of changing a pool's units. Pending purchases add capacity once paid.
    - `computers` (integer): Number of Computers deleted with the pool. May be omitted.
    - `deleted` (boolean): Whether this request deleted the pool. May be omitted.
    - `dry_run` (boolean): Whether the result is a preview. May be omitted.
    - `from_units` (integer, always present): Pool's units before this request.
    - `grow` (object): How additional units are supplied. May be omitted.
      - `bought` (object, always present): New capacity needed for the increase.
        - `memory_bytes` (integer, always present): RAM allocation in bytes.
        - `storage_bytes` (integer, always present): Included storage in bytes.
        - `units` (integer, always present): Number of units.
        - `vcpus` (integer, always present): vCPU allocation.
      - `charged_cents` (integer): Amount charged now, or previewed, in cents. May be omitted.
      - `from_unused` (object, always present): Existing purchased capacity assigned to the increase.
        - `memory_bytes` (integer, always present): RAM allocation in bytes.
        - `storage_bytes` (integer, always present): Included storage in bytes.
        - `units` (integer, always present): Number of units.
        - `vcpus` (integer, always present): vCPU allocation.
      - `kind` (string): New purchases' billing model. May be omitted.
      - `plans` (object[]): Plans bought to supply that capacity. May be omitted.
        - `items` (object): A plan purchased or proposed for a pool.
          - `charged_cents` (integer): Amount charged now, or its preview, in cents. May be omitted.
          - `checkout_url` (string): Checkout page when payment is required. May be omitted.
          - `invoice_url` (string): Invoice page when payment needs your action. May be omitted.
          - `plan` (integer, always present): Plan number.
          - `price_micros` (integer, always present): Price per billing period, in millionths of a dollar. The enclosing result specifies the billing model.
          - `purchase` (string): Capacity purchase ID. May be omitted.
          - `units` (integer, always present): Capacity units supplied by the plan.
          - `unknown` (boolean): Whether the payment outcome is uncertain. Read capacity before buying again. May be omitted.
      - `price_micros` (integer, always present): New purchases' combined hourly or monthly price, in millionths of a dollar.
    - `id` (string, always present): Pool ID.
    - `memory_bytes` (integer, always present): Resulting RAM in bytes, once pending payments complete.
    - `message` (string): Effects a deletion preview would have. May be omitted.
    - `pending` (boolean): True when purchased capacity still awaits payment. May be omitted.
    - `pool` (string, always present): Pool name.
    - `release` (object): Purchase releases or reductions. May be omitted.
      - `changes` (object[] | null, always present): Each purchase released or reduced, with any individual error.
        - `items` (object): A purchase's release or reduction during a pool resize.
          - `at` (string (date-time)): When the release or reduction takes effect. May be omitted.
          - `error` (object): Reason this purchase change failed. Other purchases can succeed independently. May be omitted.
            - `action` (object): A suggested command addressing the problem. May be omitted.
            - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
            - `message` (string, always present): What happened and any action needed from you.
            - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
            - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
            - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
            - `url` (string): Payment page for a payment-required response. May be omitted.
          - `kind` (string, always present): Billing model.
          - `plan` (integer, always present): Plan before the change.
          - `price_micros` (integer, always present): Previous hourly or monthly price, in millionths of a dollar.
          - `purchase` (string, always present): Purchase ID.
          - `refunded_cents` (integer): Any immediate refund, in cents. May be omitted.
          - `to_plan` (integer): Smaller plan after the change. Absent when the purchase is released entirely. May be omitted.
          - `to_price_micros` (integer, always present): Resulting hourly or monthly price, in millionths of a dollar.
          - `units` (integer, always present): Units this purchase change releases.
      - `freed_units` (integer, always present): Units returned by the pool.
      - `from` (string (date-time)): Time the final scheduled release stops being billed. May be omitted.
      - `renewal_micros_after` (integer, always present): Account's monthly renewal total after the release, in millionths of a dollar.
      - `renewal_micros_before` (integer, always present): Account's monthly renewal total before the release, in millionths of a dollar.
      - `stays_unused_units` (integer, always present): Returned units still billed because purchase sizes do not match the release.
      - `units` (integer, always present): Returned units that stop being paid for.
    - `request_id` (string, always present): Request ID for this pool resize.
    - `storage_bytes` (integer, always present): Resulting included storage in bytes, once pending payments complete.
    - `units` (integer, always present): Requested resulting units. Zero represents deletion.
    - `vcpus` (integer, always present): Resulting vCPU allocation, or the proposed allocation in a preview.
  - `alternative-3` (object): A preview of the requested change.
    - `changes` (string[]): Proposed effects and losses. May be omitted.
    - `dry_run` (boolean, always present): True for a preview; no changes are made.
    - `message` (string, always present): What the request would do.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The 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.

## Examples

```sh tab="heaven CLI"
heaven pool delete POOL
  [--release]
  [--dry-run]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool delete POOL
  [--release]
  [--dry-run]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/pool/delete \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{"pool": "web"}'
```

```json tab="MCP"
{ "tool": "pool_delete",
  "arguments": { "pool": "web" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "billed": [
      {
        "created_at": "2026-11-16T12:00:00Z",
        "id": "cap-c28c4698bd25616f",
        "kind": "hourly",
        "memory_bytes": 8589934592,
        "pays_micros": 41096,
        "plan": 1,
        "pools": [],
        "state": "active",
        "storage_bytes": 100000000000,
        "terms": {
          "amount_micros": 41096,
          "currency": "usd",
          "egress_gb": 500,
          "model": "hourly",
          "plan": 1,
          "rate_card": {
            "egress_micros_per_gb": 50000,
            "hourly_minimum_minutes": 60
          },
          "storage_gb": 100,
          "units": 1
        },
        "vcpus": 2
      }
    ],
    "computers": 2,
    "pool": "web"
  }
}
```
