# List plans

URL: https://heaven.dev/docs/reference/capacity/plan-view
Updated: 2026-11-21

List capacity plans and their prices, sizes, billing options and availability for your account.

`GET /v1/plan/`

## Returns

- `data` (object, always present): Plans and prices offered to this account.
  - `egress_micros_per_gb` (integer, always present): Internet egress overage price per decimal gigabyte, in millionths of a dollar.
  - `plans` (object[] | null, always present): Available plan definitions, including approval and current capacity availability.
    - `items` (object): A plan's capacity, prices and availability. Prices are millionths of a US dollar.
      - `approval` (boolean): Whether buying this plan requires approval. May be omitted.
      - `approved` (boolean): Whether this account has that approval. May be omitted.
      - `egress_bytes` (integer, always present): Monthly internet egress added to the account's allowance, in bytes.
      - `hourly_micros` (integer, always present): Hourly price for this account.
      - `hourly_passes_monthly_hours` (integer, always present): Hours held in a month beyond which hourly billing costs more than monthly.
      - `memory_bytes` (integer, always present): Plan's RAM allocation, in bytes.
      - `monthly_micros` (integer, always present): Monthly price for this account.
      - `no_room` (boolean): Whether all placements lack room for a new purchase. An existing purchase may still have room to grow. May be omitted.
      - `plan` (integer, always present): Plan number accepted by purchase commands.
      - `public_ports` (integer, always present): Public port allowance for an account holding only this plan in a placement.
      - `storage_bytes` (integer, always present): Plan's included storage, in bytes.
      - `units` (integer, always present): Number of capacity units in this plan.
      - `vcpus` (integer, always present): Plan's vCPU allocation.

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

- API key permission: `plan view`.

## Examples

```sh tab="heaven CLI"
heaven plan view
```

```sh tab="SSH"
ssh cli@heaven.dev plan view
```

```sh tab="cURL"
curl https://heaven.dev/v1/plan/ \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "plan_view",
  "arguments": {  } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "egress_micros_per_gb": 50000,
    "plans": [
      {
        "egress_bytes": 500000000000,
        "hourly_micros": 41096,
        "hourly_passes_monthly_hours": 487,
        "memory_bytes": 8589934592,
        "monthly_micros": 20000000,
        "plan": 1,
        "public_ports": 5,
        "storage_bytes": 100000000000,
        "units": 1,
        "vcpus": 2
      },
      {
        "egress_bytes": 1000000000000,
        "hourly_micros": 82192,
        "hourly_passes_monthly_hours": 487,
        "memory_bytes": 17179869184,
        "monthly_micros": 40000000,
        "plan": 2,
        "public_ports": 6,
        "storage_bytes": 250000000000,
        "units": 2,
        "vcpus": 4
      },
      {
        "egress_bytes": 2000000000000,
        "hourly_micros": 164384,
        "hourly_passes_monthly_hours": 487,
        "memory_bytes": 34359738368,
        "monthly_micros": 80000000,
        "no_room": true,
        "plan": 3,
        "public_ports": 8,
        "storage_bytes": 500000000000,
        "units": 4,
        "vcpus": 8
      }
    ]
  }
}
```
