Balance
Get your current credit balance with EUR conversion, 30-day burn rate, projected runway in days, and your API tier via GET /v1/credits/balance.
The credit balance endpoint (GET /v1/credits/balance) returns how many credits your account has left, enriched with the EUR-equivalent balance, a 30-day burn rate, projected runway in days, and your current API tier. Credits are the universal billing unit for all Talonic operations, so one call answers "how much can I still process". It requires an API key with the read scope.
Call it to monitor consumption, alert on low balance, and plan capacity. Because the response already includes burn rate and runway, an agent can decide whether to trigger an auto top-up (POST /v1/billing/topup) or hand a human an upgrade link without any client-side math.
- balance_credits — Current credit balance as an integer.
- burn_rate_30d_credits — Credits consumed in the last 30 days for trend analysis.
- projected_runway_days — Estimated days remaining at the current burn rate.
- tier — Your current API tier (e.g.
free,starter,growth), which determines rate limits and features.
/v1/credits/balancecURL — Check your credit balance
curl https://api.talonic.com/v1/credits/balance \
-H "Authorization: Bearer $TALONIC_API_KEY"Response
Response fields
Response
{
"balance_credits": 4250,
"balance_eur": 4.25,
"burn_rate_30d_credits": 1800,
"projected_runway_days": 70,
"tier": "starter",
"tier_resets_at": "2026-08-01T00:00:00.000Z"
}X-Talonic-Balance-Credits response header on POST /v1/extract reports the remaining balance after each request, so agents rarely need to poll this endpoint in a tight loop.Errors
Error responses
Frequently asked questions
What does projected_runway_days: -1 mean?+
When does the API tier reset?+
tier_resets_at field.How is the EUR balance calculated?+
balance_eur is computed by dividing balance_credits by the credits-per-EUR conversion rate (1,000 credits per EUR at the standard rate). The same rate is published by the unauthenticated GET /v1/pricing endpoint as credits_per_eur.What can I do when my credit balance runs low?+
PATCH /v1/billing/settings so an agent can replenish credits autonomously with POST /v1/billing/topup, or fetch GET /v1/billing/upgrade-link to hand a human a link to upgrade the plan or add a payment method.