Balance
Read your current credit balance.
GET /api/v1/balance HTTP/1.1
Host: citeflow.io
Authorization: Bearer ckf_…Costs 0 credits. Use this as a pre-flight check before POST /audit
so dashboards can surface an out-of-credits warning before the call
would 402.
Response — 200
{
"data": {
"balance": 4820,
"balance_usd": "$48.20",
"lifetime_purchased": 4900,
"lifetime_consumed": 80,
"low_balance_threshold": 500
},
"request_id": "req_01jbq6t8…"
}| Field | Meaning |
|---|---|
balance | Current credits available (1 credit = $0.01). |
balance_usd | USD-formatted convenience field. balance is authoritative. |
lifetime_purchased | Sum of all purchases ever (used for tier derivation). |
lifetime_consumed | Sum of all usage-type ledger debits ever. |
low_balance_threshold | Threshold at which a balance.low webhook fires. Configurable in dashboard. |
Tier derivation
CiteFlow doesn't ship a "current tier" field today because tier is
derived from lifetime_purchased:
| Lifetime purchased | Tier |
|---|---|
| < 20,900 | Starter |
| ≥ 20,900 | Growth |
| ≥ 54,900 | Scale |
| ≥ 100,000 | Enterprise |
Tier affects rate limits — see Rate limits.
Webhook companion
Configure balance.low in your webhook endpoint and CiteFlow will
notify you once per threshold crossing (debounced 24h). Combined
with top-up, this
lets your dashboard auto-replenish.
Rate limit
60 requests/minute, every tier. Polling more frequently than that isn't useful — the balance only changes on audit, top-up, or refund.