# Read an organization's usage

URL: https://heaven.dev/docs/reference/organizations/usage
Updated: 2026-11-21

Read an organization's pool usage and capacity charges for the month so far, starting at midnight UTC on the first. Requires billing owner or organization admin access.

`GET /v1/organization/?view=usage`

## 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 organization's spending, pool activity and measured use over the selected month.
  - `balance_micros` (integer, always present): Current wallet balance in millionths of a dollar.
  - `capacity` (object[] | null, always present): Capacity purchases and their costs.
    - `items` (object): One capacity purchase's cost in the reporting period.
      - `charged_micros` (integer, always present): Amount charged to the wallet in this period, in millionths of a dollar.
      - `id` (string, always present): Purchase ID.
      - `kind` (string, always present): Cost category or billing model.
      - `monthly_micros` (integer): Purchase's current monthly price, in millionths of a dollar. May be omitted.
      - `plan` (integer): Plan number, where applicable. May be omitted.
      - `region` (string): Purchase's region. May be omitted.
      - `released` (boolean): Whether this purchase was released. May be omitted.
  - `charged_micros` (integer, always present): Wallet charges in the reporting period, in millionths of a dollar.
  - `from` (string (date-time), always present): Start of the reporting period.
  - `history_unavailable` (boolean): Whether usage history could not be read. May be omitted.
  - `pools` (object[] | null, always present): Activity and measured usage for each pool.
    - `items` (object): A pool's activity and use in the reporting period. Null measurements are unknown.
      - `cpu_vcpus_avg` (number | null, always present): Average measured vCPUs in use.
      - `hours` (map<string, number> | null, always present): Hours recorded in each power state.
      - `id` (string, always present): Pool ID.
      - `lifecycle` (string, always present): Pool's lifecycle state.
      - `net_rx_bytes` (integer | null, always present): Measured bytes received.
      - `net_tx_bytes` (integer | null, always present): Measured bytes sent.
      - `pool` (string, always present): Pool name.
      - `power` (string, always present): Pool's power setting.
      - `provided` (boolean): Whether Heaven provides the capacity without charging the organization. May be omitted.
      - `storage` (string): Current files and snapshots against included storage, as readable text. May be omitted.
  - `to` (string (date-time), always present): End of the reporting period.

## 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: `organization usage`.

## Examples

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

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

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

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

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "balance_micros": 1010000000,
    "capacity": [
      {
        "charged_micros": 0,
        "id": "cap-26f3e82b1d102ce3",
        "kind": "hourly",
        "plan": 1
      }
    ],
    "charged_micros": 0,
    "from": "2026-11-01T00:00:00Z",
    "pools": [
      {
        "cpu_vcpus_avg": null,
        "hours": {
          "running": 0,
          "stopped": 0
        },
        "id": "pool-423ea29bf8ba6f36",
        "lifecycle": "active",
        "net_rx_bytes": null,
        "net_tx_bytes": null,
        "pool": "web",
        "power": "running"
      }
    ],
    "to": "2026-11-16T12:00:00Z"
  }
}
```
