GET /api/agent/account-balances
Returns balance-sheet (asset/liability/equity) GL account balances as-at asAtDate (default today), cached by date. Requires the READ_ACCOUNTS scope (opt-in, off by default). Sensitive accounts (XeroAccount.isSensitive) have their name rewritten to "Sensitive account" and code cleared when the key lacks READ_SENSITIVE; the balance is never masked.
Auth
- Required scope:
READ_ACCOUNTS - Header:
Authorization: Bearer cr_live_<prefix>_<secret>
Query parameters
| Name | Type | Required | Notes |
|---|---|---|---|
asAtDate | string | no | Balance-sheet date (YYYY-MM-DD). Defaults to today. Past dates are immutable and served from cache forever; today's data is refreshed when older than 12 hours. |
forceRefresh | boolean | no | When true, bypass the date cache and re-fetch live from Xero. Useful after a significant mid-day balance movement. |
Responses
200 — Balance-sheet account balances for the requested date
Body:
| Field | Type | Required | Notes |
|---|---|---|---|
asAtDate | string (date) | yes | The balance-sheet date these balances are as-at (YYYY-MM-DD). |
currency | string | yes | Org base currency (3-letter ISO code). |
accounts | array of object | yes | |
redactedItemCount | integer | yes | Number of accounts whose name was rewritten to "Sensitive account" and code cleared due to XeroAccount.isSensitive gating. Always 0 when the key carries READ_SENSITIVE. |
xeroAlert | XeroAlert | no | |
billingAlert | BillingAlert | no |
400 — Invalid asAtDate — must be a valid YYYY-MM-DD date string.
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
401 — Missing / invalid bearer, wrong prefix, secret mismatch, or revoked key
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
403 — Key lacks the required READ_ACCOUNTS scope
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
429 — Per-minute burst or daily quota exhausted
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
Response headers
Every successful response carries X-CashRunway-Subscription, X-CashRunway-Plan, X-CashRunway-Quota-Remaining, and X-CashRunway-Quota-Reset. Trialing subscriptions also include X-CashRunway-Trial-Days-Remaining. See the overview for details.