# Read this month's cost

URL: https://heaven.dev/docs/reference/billing/cost
Updated: 2026-11-21

Read this month's costs and projected total by day and pool. The projection assumes current usage continues and includes scheduled purchase changes. Future egress overage is outside the projection.

`GET /v1/organization/billing/?view=cost`

## 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): Recorded and estimated costs for a calendar month. Monetary amounts are millionths of a US dollar.
  - `by_end_micros` (integer, always present): Estimated total cost by the month's end.
  - `days` (object[] | null, always present): Daily costs, including estimates for time still to come.
    - `items` (object): A day's costs, in millionths of a US dollar.
      - `date` (string, always present): UTC calendar date.
      - `egress_micros` (integer, always present): Cost of internet egress overage.
      - `estimated` (boolean, always present): Whether this day includes an estimate.
      - `estimated_micros` (integer, always present): Portion of the total estimated for time still to come.
      - `pools` (object[] | null, always present): Each pool's cost for the day.
        - `items` (object): A pool's cost for one day.
          - `micros` (integer, always present): Pool's cost in millionths of a dollar.
          - `pool_id` (string, always present): Pool ID.
      - `total_micros` (integer, always present): Day's total, including any estimated portion.
      - `unused_micros` (integer, always present): Cost of purchased capacity not allocated to pools.
  - `from` (string (date-time), always present): Start of that month in UTC.
  - `lines` (object[] | null, always present): Costs by pool, unused capacity and egress.
    - `items` (object): Monthly costs for a pool, unused capacity or egress. Monetary amounts are millionths of a US dollar.
      - `billed` (string, always present): Payment source: monthly, hourly, both, provided capacity or wallet. Empty when nothing is held.
      - `by_end_micros` (integer, always present): Estimated total by month's end.
      - `deleted` (boolean): True for a pool deleted during this month. May be omitted.
      - `hourly_micros` (integer, always present): Current cost per hour attributed to this line.
      - `kind` (string, always present): `pool`, `unused` or `egress`, identifying what this line measures.
      - `memory_bytes` (integer): Unused purchased RAM in bytes, for unused-capacity lines. May be omitted.
      - `monthly_micros` (integer, always present): Current monthly capacity cost attributed to this line.
      - `paid_at` (string (date-time)): When the current monthly period was paid. May be omitted.
      - `pool` (string): Pool name. May be omitted.
      - `pool_id` (string): Pool's ID for a pool line. May be omitted.
      - `so_far_micros` (integer, always present): Cost recorded so far this month.
      - `vcpus` (integer): Unused purchased vCPUs, for unused-capacity lines. May be omitted.
  - `month` (string, always present): Selected calendar month.
  - `now` (string (date-time), always present): When these costs were read.
  - `so_far_micros` (integer, always present): Recorded cost so far in the month.
  - `spend_alert_micros` (integer | null, always present): Monthly alert threshold, or null without an alert.
  - `to` (string (date-time), always present): Start of the following month in UTC.

## 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: `billing cost`.

## Examples

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

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

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

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

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "by_end_micros": 14300000,
    "days": [
      {
        "date": "2026-11-01",
        "egress_micros": 0,
        "estimated": false,
        "estimated_micros": 0,
        "pools": [],
        "total_micros": 0,
        "unused_micros": 0
      },
      {
        "date": "2026-11-02",
        "egress_micros": 0,
        "estimated": false,
        "estimated_micros": 0,
        "pools": [],
        "total_micros": 0,
        "unused_micros": 0
      },
      {
        "date": "2026-11-03",
        "egress_micros": 0,
        "estimated": false,
        "estimated_micros": 0,
        "pools": [],
        "total_micros": 0,
        "unused_micros": 0
      }
    ],
    "from": "2026-11-01T00:00:00Z",
    "lines": [
      {
        "billed": "",
        "by_end_micros": 0,
        "hourly_micros": 0,
        "kind": "pool",
        "monthly_micros": 0,
        "pool": "web",
        "pool_id": "pool-d5e940c25e235d0a",
        "so_far_micros": 0
      },
      {
        "billed": "",
        "by_end_micros": 14300000,
        "hourly_micros": 0,
        "kind": "unused",
        "monthly_micros": 0,
        "so_far_micros": 0
      },
      {
        "billed": "wallet",
        "by_end_micros": 0,
        "hourly_micros": 0,
        "kind": "egress",
        "monthly_micros": 0,
        "so_far_micros": 0
      }
    ],
    "month": "2026-11",
    "now": "2026-11-16T12:00:00Z",
    "so_far_micros": 0,
    "spend_alert_micros": null,
    "to": "2026-12-01T00:00:00Z"
  }
}
```
