Skip to main content

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.
GET/v1/credits/balance

cURL — Check your credit balance

curl https://api.talonic.com/v1/credits/balance \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

balance_creditsintegerCurrent credit balance.
balance_eurnumberCredit balance converted to EUR at the configured rate.
burn_rate_30d_creditsintegerCredits consumed over the last 30 days.
projected_runway_daysintegerEstimated days of runway at the current burn rate. -1 if burn rate is zero.
tierstringCurrent API tier (e.g. free, starter, growth).
tier_resets_atstringISO 8601 timestamp when the tier resets (1st of next month UTC).

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"
}
The balance is also pushed to you for free on every extraction: the 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

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What does projected_runway_days: -1 mean?+
A value of -1 indicates that your burn rate over the last 30 days is zero, so runway cannot be projected. This typically means no API calls were made during the period.
When does the API tier reset?+
Tiers reset on the 1st of each month at midnight UTC. The exact reset timestamp is returned in the `tier_resets_at` field.
How is the EUR balance calculated?+
The `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?+
Enable auto top-up via `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.

Related

Transaction History
Usage Summary by Operation
Auto Top-Up
Pricing Catalog