# Resize a pool

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

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.

`POST /v1/pool/modify`

## Parameters

- `pool` (string, required): Pool name or ID.
- `memory` (string): New total RAM from existing capacity in multiples of 8 GiB, with 2 vCPUs and corresponding storage per unit.
- `units` (string): 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.
- `buy` (object)
  - `plan` (string): Plan number from `plan view`. The entire plan is added to the pool on its server.
  - `monthly` (boolean): With `buy.plan`, pay monthly for new capacity (default).
  - `hourly` (boolean): With `buy.plan`, pay for new capacity from your wallet by the minute, with a minimum charge of one hour.
- `buy_rest` (string): Billing model for capacity needed beyond unused units. Give monthly or hourly.
- `months` (string): Length of a new monthly purchase's prepaid term with `buy.plan`. Choose 1 (default) or 12.
- `offer` (string): Offer code for new capacity bought for this resize.
- `release` (boolean): Release capacity freed by shrinking, where whole plans allow. Hourly billing ends immediately; monthly billing ends after the paid period.
- `dry_run` (boolean): Preview the resulting size, purchases and releases. Available with `buy.plan` or `units`, or when using `release: true`.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): Pool capacity and any purchases or releases.
  - `alternative-1` (object): A pool's resulting or proposed capacity and purchase. Pending payment must complete before the pool is created or enlarged.
    - `charged_cents` (integer): Immediate charge, or the previewed charge, in cents. May be omitted.
    - `checkout_url` (string): First monthly purchase's payment page. May be omitted.
    - `dry_run` (boolean): True when no pool or purchase was made. May be omitted.
    - `grows` (boolean): True when a purchase adds capacity to an existing pool after it becomes active. May be omitted.
    - `id` (string): Pool ID, when a pool has been created. May be omitted.
    - `invoice_url` (string): Payment page for an additional purchase needing your action. May be omitted.
    - `kind` (string): Billing model. May be omitted.
    - `memory_bytes` (integer): Pool's resulting RAM allocation, in bytes, including the increase once paid. May be omitted.
    - `plan` (integer): Purchased plan number. May be omitted.
    - `pool` (string, always present): Pool name.
    - `price_micros` (integer): Purchase's hourly or monthly price, in millionths of a dollar. May be omitted.
    - `purchase` (string): Capacity purchase made for this pool. May be omitted.
    - `storage_bytes` (integer): Resulting included storage, in bytes. May be omitted.
    - `unknown` (boolean): Whether the payment response was lost. Read `capacity view` before retrying. May be omitted.
    - `vcpus` (integer): Resulting vCPU allocation. May be omitted.
    - `wallet_micros` (integer): Wallet balance after an hourly purchase, in millionths of a dollar. May be omitted.
  - `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.

## 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.
- 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`.

## Examples

```sh tab="heaven CLI"
heaven pool resize POOL
  [--memory SIZE]
  [--units N]
  [--buy PLAN]
  [--buy-rest monthly|hourly]
  [--monthly]
  [--hourly]
  [--months MONTHS]
  [--offer OFFER]
  [--release]
  [--dry-run]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool resize POOL
  [--memory SIZE]
  [--units N]
  [--buy PLAN]
  [--buy-rest monthly|hourly]
  [--monthly]
  [--hourly]
  [--months MONTHS]
  [--offer OFFER]
  [--release]
  [--dry-run]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/pool/modify \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  -H "Idempotency-Key: resize-web" \
  --json '{"action": "resize", "pool": "web", "memory": "16GB"}'
```

```json tab="MCP"
{ "tool": "pool_resize",
  "arguments": { "pool": "web", "memory": "16GB", "request_id": "resize-web" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "id": "pool-62147045776ac3f5",
    "memory_bytes": 17179869184,
    "pool": "web",
    "storage_bytes": 200000000000,
    "vcpus": 4
  }
}
```
