Get Books Health Check Overview
GET/api/ledger/health-check
Everything about the books health check: the accounting connection it reads, the latest run in full, run history, settings (grade bands, account → channel map, footer), the default window (the last 12 complete months) and how many metered provider reads that window would cost.
accounting:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
The health check is a read-only comparison of the account's own figures with its Xero or QuickBooks books, in four sections: income and the chart of accounts, by channel, COGS, and balance sheet. Each section has a grade band and the trust level of the figures beside it. Nothing is ever written to the provider.
latest is the running run when there is one, otherwise the newest run; when the newest run failed (e.g. a base-currency mismatch), latest is the last finished run and latest_failure points at the failed one. A run whose worker stopped is closed as partial (error.kind = interrupted) when read.
connection is null when no Xero or QuickBooks connection can read a trial balance.
Authentication: Requires Bearer token + accounting.index permission.
Request
Responses
- 200
- 401
- 403
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.