---
title: "Live account balances (per-key quota)"
method: GET
path: "/account/balances"
tags: ["Account"]
---

# Live account balances (per-key quota)

`GET /account/balances`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/account/balances`
- Auth: one of:
  - API key in header `X-Acuris-Key`
  - HTTP bearer
  - API key in header `X-API-Key`
  - API key in query parameter `key`

The true per-key quota endpoint for the logged-in console/dashboard.
Returns all four transaction pools with their denominators, the real trial
countdown, and Stripe subscription state — reflecting reality on load
and after each call (not the frozen login-fragment snapshot).

**Auth:** the account's own API key — send `X-Acuris-Key: <key>`
(primary). `Authorization: Bearer <key>`, `X-API-Key`, or the legacy
`?key=` query param is also accepted.

**Transaction costs (Stripe-plan transactions, per call):** `validate` = 1,
`geocode` = 1, `reverse` = 1. During a trial the pool
decrements 1 regardless of endpoint weight.

Per-product daily free limits apply (check remaining via
`/validate-credits` and `/geocode-credits`); anonymous access is
rate-limited per IP.

## Response `200`

Live balances, trial countdown, and subscription state for the caller's key.

- AccountBalances
  - `key_accepted` boolean, required
  - `pools` object, required: The four independently-metered transaction pools. Each pool's `total` is the greater of the remaining balance and the trial floor (so a granted account reads N/N rather than N/1000). The `email` and `phone` pools report a `total` of 0 until they hold transactions.
    - `validation` CreditPool, required
      - `remaining` integer, required
      - `total` integer, required: Denominator; 0 for the email/phone pools until they are funded.
      - `used_pct` integer, required: Rounded percentage consumed; 0 when total is 0.
    - `geocode` CreditPool, required
      - `remaining` integer, required
      - `total` integer, required: Denominator; 0 for the email/phone pools until they are funded.
      - `used_pct` integer, required: Rounded percentage consumed; 0 when total is 0.
    - `email` CreditPool, required
      - `remaining` integer, required
      - `total` integer, required: Denominator; 0 for the email/phone pools until they are funded.
      - `used_pct` integer, required: Rounded percentage consumed; 0 when total is 0.
    - `phone` CreditPool, required
      - `remaining` integer, required
      - `total` integer, required: Denominator; 0 for the email/phone pools until they are funded.
      - `used_pct` integer, required: Rounded percentage consumed; 0 when total is 0.
  - `trial_expires_at` string, nullable: UTC trial-window end (`YYYY-MM-DD HH:MM:SS`), or null.
  - `trial_expired` boolean: True once the trial calendar window has lapsed.
  - `days_left` integer, nullable: Whole days remaining in the trial window, or null if no/unparseable expiry.
  - `subscription` object, nullable: Stripe subscription state for the account's email, or null when none exists.
    - `plan` string, nullable
    - `status` string, nullable
    - `quota_used` integer
    - `quota_limit` integer

## Other responses

- `401`: API key required, or invalid/inactive key. Body includes `key_accepted: false`.

---

[API](https://skmtc.dev/acuris-geo/apis/acuris-geo-api.md) · [All operations](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/revisions/8547b31dd96a?raw)