# Read your account

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

Read your sign-in identity and account details. The response includes the keys, billing details and settings your credential can read.

`GET /v1/account/`

## 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): Your account identity and requested details.
  - `account_id` (string, always present): Selected account's ID.
  - `addresses` (object): Static addresses held by the account. May be omitted.
    - `addresses` (object[] | null, always present): Addresses in the selected scope and their attachments.
      - `items` (object): A static IPv4 address and its attachment.
        - `account` (boolean): Whether this is the account's default address for pools in this placement. May be omitted.
        - `address` (string, always present): Static IPv4 address.
        - `available_from` (string (date-time)): When a released address becomes available to another account. May be omitted.
        - `bought_at` (string (date-time), always present): When the account acquired the address.
        - `computer` (string): Attached Computer's name. May be omitted.
        - `computer_id` (string): Attached Computer's ID. May be omitted.
        - `pool` (string): Attached pool's name. May be omitted.
        - `pool_id` (string): Attached pool's ID. May be omitted.
        - `region` (string, always present): Address's region.
        - `released_at` (string (date-time)): When the address was released. May be omitted.
    - `limit` (integer, always present): Account's static-address allowance.
  - `api_keys` (object): API key metadata. May be omitted.
    - `api_keys` (object[] | null, always present): Key metadata, permissions and lifetime.
      - `items` (object): An API key's identity, permissions and lifetime.
        - `cmds` (string[] | null, always present): Permitted commands, subject to your permissions. `*` permits all commands for a sign-in key.
        - `computer_names` (map<string, string>): Names of the Computers its scope names, by ID, those its organization still has. May be omitted.
        - `created_at` (string (date-time), always present): When the key was created.
        - `expires_at` (string (date-time) | null, always present): When the key expires, or null if it has no expiry.
        - `id` (string, always present): Key ID for editing, rotation or revocation.
        - `label` (string, always present): User-assigned label.
        - `last_used_at` (string (date-time) | null, always present): Last recorded use, or null if no use has been recorded.
        - `organization` (string): Organization the key acts in. Sign-in keys can omit this to select an organization per request. May be omitted.
        - `previous_secret_expires_at` (string (date-time)): Expiry of the replaced secret, included while it remains accepted. May be omitted.
        - `revoked_at` (string (date-time) | null, always present): When the key was revoked, or null if it has not been revoked.
        - `rotated_at` (string (date-time) | null, always present): When its secret was last rotated, or null if it has not been rotated.
        - `scope` (object): Resource restrictions in addition to your permissions. An absent scope adds no restriction. May be omitted.
          - `computers` (string[]): Computer IDs included in the key's scope. May be omitted.
          - `pools` (string[]): Pool IDs included in the key's scope. May be omitted.
          - `tags` (string[]): Tags selecting Computers the key can reach. May be omitted.
        - `token` (string): Newly issued secret, returned only on creation or rotation. May be omitted.
  - `billing` (object): Selected account's billing details. May be omitted.
    - `auto_topup_cents` (integer): Automatic top-up amount in cents. May be omitted.
    - `auto_topup_monthly_limit_cents` (integer, always present): Monthly automatic top-up ceiling, in cents.
    - `balance_micros` (integer, always present): Total remaining wallet credit, in millionths of a dollar.
    - `can_manage` (boolean, always present): Whether you can manage this account's billing.
    - `card` (object): Saved payment card. May be omitted.
      - `brand` (string): Card brand reported by the payment provider. May be omitted.
      - `exp_month` (integer): Expiration month, from 1 through 12. May be omitted.
      - `exp_year` (integer): Four-digit expiration year. May be omitted.
      - `last4` (string, always present): Last four digits of the card number.
    - `card_form` (boolean): Whether the card setup form is available. May be omitted.
    - `card_saved` (boolean, always present): Whether a payment card is saved.
    - `contacts` (string[]): Additional recipients of billing email. May be omitted.
    - `egress` (object): This month's outbound traffic usage, charges and cap. May be omitted.
      - `allowance_bytes` (integer, always present): Internet egress included for the month, in bytes.
      - `cap` (string, always present): Egress cap setting: `default`, `amount` or `off`.
      - `cap_micros` (integer): Monthly cap in millionths of a dollar. Absent when the cap is off. May be omitted.
      - `charged_micros` (integer, always present): Egress charged so far this month, in millionths of a dollar.
      - `charging` (boolean, always present): Whether egress overage is currently billed.
      - `month` (string (date-time), always present): Month being measured.
      - `not_charged_bytes` (integer): Overage bytes not charged while the wallet was past its grace period. May be omitted.
      - `over_bytes` (integer, always present): Usage above the included allowance, in bytes.
      - `projected_bytes` (integer, always present): Estimated monthly egress based on use so far, in bytes.
      - `slowed` (boolean, always present): Whether the account's internet egress is currently slowed because of its egress cap, its spending cap or its wallet state.
      - `used_bytes` (integer, always present): Internet egress used this month, in bytes.
      - `would_charge_micros` (integer): What overage would cost if charging were enabled, in millionths of a dollar. May be omitted.
    - `entries` (object[] | null, always present): Recent wallet ledger entries.
      - `items` (object): One wallet ledger entry.
        - `amount_micros` (integer, always present): Signed change in wallet balance, in millionths of a dollar.
        - `at` (string (date-time), always present): When the entry was recorded.
        - `kind` (string, always present): Reason for the credit or debit.
        - `pool` (string): Pool associated with the entry, when present. May be omitted.
    - `held` (boolean): Whether billing has placed the account on hold. May be omitted.
    - `lasts_hours` (number): Estimated wallet lifetime in hours at current spending. May be omitted.
    - `next_renewal` (string (date-time)): When the next monthly renewal is due. May be omitted.
    - `notices` (string[] | null, always present): Billing issues or changes needing attention.
    - `paid_micros` (integer, always present): Remaining purchased wallet credit, in millionths of a dollar.
    - `pay_by` (string): Account's payment method. May be omitted.
    - `payments_off` (boolean): Whether payments are disabled. May be omitted.
    - `per_hour_micros` (integer, always present): Hourly wallet spending, in millionths of a dollar.
    - `promo_expiring` (object[]): Promotional credits expiring soon. May be omitted.
      - `items` (object): A wallet credit grant.
        - `amount_micros` (integer, always present): Original credit amount in millionths of a dollar.
        - `created_at` (string (date-time), always present): When the credit was granted.
        - `expires_at` (string (date-time)): When unused credit expires, if an expiry is set. May be omitted.
        - `id` (string, always present): Credit grant's ID.
        - `refundable` (boolean, always present): Whether this credit is eligible for a refund.
        - `remaining_micros` (integer, always present): Credit still available, in millionths of a dollar.
        - `scope` (string[]): Spending categories this credit can pay for. May be omitted.
        - `source` (string, always present): Origin of this credit.
    - `promo_micros` (integer, always present): Remaining promotional wallet credit, in millionths of a dollar.
    - `purchases` (object[] | null, always present): Purchases being billed and any scheduled changes.
      - `items` (object): A billed capacity purchase and its pending changes.
        - `amount_micros` (integer, always present): Price per billing period, in millionths of a dollar.
        - `change` (string): Scheduled change to this purchase. May be omitted.
        - `change_at` (string (date-time)): When the scheduled change takes effect. May be omitted.
        - `change_plan` (integer): Plan selected by a scheduled resize. May be omitted.
        - `id` (string, always present): Capacity purchase ID.
        - `model` (string, always present): Billing model.
        - `pending` (boolean): Whether the first payment is pending. May be omitted.
        - `plan` (integer, always present): Purchased plan number.
        - `pools` (string[] | null, always present): Pools that can use capacity from this purchase.
        - `region` (string): Purchase's region. May be omitted.
        - `switch_saves_micros` (integer): Estimated monthly savings from switching to monthly billing, in millionths of a dollar. May be omitted.
    - `renewal_micros` (integer, always present): Account's monthly renewal total, in millionths of a dollar.
    - `spend_alert_micros` (integer | null, always present): Monthly spending alert threshold in millionths of a dollar; null disables alerts.
    - `spending_cap_micros` (integer | null, always present): Monthly spending cap in millionths of a dollar, past which nothing is charged; null for none.
    - `subscription_status` (string): Payment provider's current subscription state. May be omitted.
    - `time_zone` (string, always present): Account's time zone for billing communications.
    - `usage_emails` (boolean, always present): Whether monthly usage emails are enabled.
  - `defaults` (object): Default setup script. May be omitted.
    - `value` (string, always present): Saved script text. An empty value means no account default is set.
  - `email` (string): Your verified email address, when one is recorded. May be omitted.
  - `invitations` (object[]): Invitations you can accept or decline. May be omitted.
    - `items` (object): An organization or team invitation awaiting your decision.
      - `expires_at` (string (date-time), always present): When the invitation expires.
      - `id` (string, always present): Invitation ID.
      - `invited_by` (string): Inviter's email, when a person sent it. May be omitted.
      - `invited_by_name` (string): Inviter's display name, when available. May be omitted.
      - `organization` (string, always present): Organization the invitation joins.
      - `role` (string, always present): Offered organization role.
      - `team` (string): Team being joined, as `ORGANIZATION@TEAM`. May be omitted.
      - `team_role` (string): Offered team role, when applicable. May be omitted.
      - `teams` (string[]): Additional teams included in the invitation. May be omitted.
  - `name` (string | null, always present): Your saved display name, or null without one.
  - `picture` (string | null, always present): Your profile picture URL, or null without one.
  - `ssh_keys` (object): Registered SSH keys. May be omitted.
    - `keys` (object[] | null, always present): Each key's identity and any Computer or tag restriction.
      - `items` (object): A registered SSH public key and its access restrictions.
        - `computer` (object): Single Computer this key can reach, when it is limited to one. May be omitted.
          - `id` (string, always present): Selected Computer's ID.
          - `name` (string, always present): Current name; empty during deletion or after you lose access.
        - `created_at` (string (date-time)): Time the key was added. May be omitted.
        - `fingerprint` (string, always present): Public key fingerprint.
        - `id` (string, always present): Registered key's ID.
        - `label` (string, always present): User-assigned label.
        - `last_used_at` (string (date-time) | null, always present): Last recorded SSH sign-in; null if none is recorded. Updates can take five minutes.
        - `public_key` (string, always present): SSH public key.
        - `tag` (string): Tag limiting the key to matching Computers, when set. May be omitted.
  - `unavailable` (string[]): Requested parts that could not be read. May be omitted.
  - `user_id` (string, always present): Your user ID.
  - `withheld` (string[]): Requested parts that your credential or role cannot read. 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: `account view`.

## Examples

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

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

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

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

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "account_id": "3b1afaa9-93ee-4a03-ae85-b180e7db2813",
    "addresses": {
      "addresses": [],
      "limit": 2
    },
    "api_keys": {
      "api_keys": []
    },
    "billing": {
      "auto_topup_monthly_limit_cents": 50000,
      "balance_micros": 1010000000,
      "can_manage": true,
      "card_saved": false,
      "entries": [
        {
          "amount_micros": 1000000000,
          "at": "2026-11-16T12:00:00Z",
          "kind": "credit"
        },
        {
          "amount_micros": 10000000,
          "at": "2026-11-16T12:00:00Z",
          "kind": "credit"
        }
      ],
      "lasts_hours": 24576.601129063656,
      "notices": [],
      "paid_micros": 0,
      "payments_off": true,
      "per_hour_micros": 41096,
      "promo_micros": 1010000000,
      "purchases": [
        {
          "amount_micros": 41096,
          "id": "cap-9ad521c5ea8c1355",
          "model": "hourly",
          "plan": 1,
          "pools": [
            "web"
          ]
        }
      ],
      "renewal_micros": 0,
      "spend_alert_micros": null,
      "spending_cap_micros": null,
      "time_zone": "UTC",
      "usage_emails": true
    },
    "email": "you@example.com",
    "invitations": [],
    "name": null,
    "picture": null,
    "ssh_keys": {
      "keys": []
    },
    "user_id": "ee5d6ad6-52c0-4784-a208-2ab94978fea0"
  }
}
```
