# List charges

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

List wallet transactions by pool and hour, newest first. Use `before` with the returned cursor for older entries.

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

## Parameters

- `before` (string): Pagination cursor from the previous response. Returns older entries.
- `limit` (string): Maximum transactions per page. Defaults to 50. Maximum 500.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): A page of wallet credits and charges.
  - `entries` (object[] | null, always present): Ledger entries in this page.
    - `items` (object): One recorded top-up, credit or charge.
      - `amount_micros` (integer, always present): Signed wallet amount, in millionths of a dollar.
      - `at` (string (date-time), always present): When the entry was recorded.
      - `id` (string, always present): Ledger entry's ID.
      - `kind` (string, always present): Reason for the entry.
      - `period_end` (string (date-time)): End of the period covered by a charge. May be omitted.
      - `period_start` (string (date-time)): Beginning of the period covered by a charge. May be omitted.
      - `pool` (string): Pool associated with the entry. May be omitted.
  - `next` (string): Cursor for `before` to fetch the next older page. Absent on the last page. May be omitted.

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

## Examples

```sh tab="heaven CLI"
heaven billing history
  [--before BEFORE]
  [--limit N]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev billing history
  [--before BEFORE]
  [--limit N]
  [--organization ORGANIZATION]
```

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

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

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "entries": [
      {
        "amount_micros": 1000000000,
        "at": "2026-11-16T12:00:00Z",
        "id": "c88d8092-0718-4eb4-aeef-072f4be44b89",
        "kind": "credit"
      },
      {
        "amount_micros": 10000000,
        "at": "2026-11-16T12:00:00Z",
        "id": "b3959c69-6e39-4903-afe7-79bef0dcc17e",
        "kind": "credit"
      }
    ]
  }
}
```
