# Read your capacity

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

List your organization's capacity purchases and the capacity still available for pools on each server. Use purchase IDs here to resize, switch or release capacity.

`GET /v1/organization/capacity/`

## Parameters

- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): The account's capacity purchases and pool allocations.
  - `had_computer` (boolean, always present): Whether this account has ever created a Computer, including a deleted one.
  - `purchases` (object[] | null, always present): Purchases held by the account, including payment-pending or lapsed purchases.
    - `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.
  - `servers` (object[] | null, always present): Capacity totals grouped by where the account's pools can use them.
    - `items` (object): Purchased and allocated capacity for pools in one placement.
      - `memory_allocated_bytes` (integer, always present): Purchased RAM allocated to pools here, in bytes.
      - `memory_bought_bytes` (integer, always present): RAM purchased here, in bytes.
      - `pools` (string[] | null, always present): Pools using this placement's capacity.
      - `region` (string): Region containing these pools. May be omitted.
      - `storage_allocated_bytes` (integer, always present): Purchased storage allocated to pools here, in bytes.
      - `storage_bought_bytes` (integer, always present): Storage purchased here, in bytes.
      - `vcpus_allocated` (integer, always present): Purchased vCPUs allocated to pools here.
      - `vcpus_bought` (integer, always present): vCPUs purchased here.
  - `storage` (object[] | null, always present): Storage included and used in each placement group.
    - `items` (object): The account's storage in one placement, including stopped pools.
      - `included_bytes` (integer, always present): Storage included by the account's purchases here, in bytes.
      - `region` (string): Region of this storage. May be omitted.
      - `used_bytes` (integer, always present): Files and snapshots stored here as last measured, in bytes.

## 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: `capacity view`.

## Examples

```sh tab="heaven CLI"
heaven capacity view
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev capacity view
  [--organization ORGANIZATION]
```

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

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

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "had_computer": true,
    "purchases": [
      {
        "created_at": "2026-11-16T12:00:00Z",
        "id": "cap-fce0ee0ca1dca90f",
        "kind": "hourly",
        "memory_bytes": 8589934592,
        "pays_micros": 41096,
        "plan": 1,
        "pools": [
          "web"
        ],
        "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
      }
    ],
    "servers": [
      {
        "memory_allocated_bytes": 8589934592,
        "memory_bought_bytes": 8589934592,
        "pools": [
          "web"
        ],
        "storage_allocated_bytes": 100000000000,
        "storage_bought_bytes": 100000000000,
        "vcpus_allocated": 2,
        "vcpus_bought": 2
      }
    ],
    "storage": [
      {
        "included_bytes": 100000000000,
        "used_bytes": 0
      }
    ]
  }
}
```
