talonic_get_balance

Returns the workspace's current credit balance, EUR value, 30-day burn rate, projected runway in days, API tier, and the timestamp of the next monthly tier reset. Use it for budget-aware behaviour: read the balance before scheduling a large batch, or after a sequence of extractions to track spend.

When to use

The user asks how many credits or how much budget they have left.
Before kicking off a large or expensive operation (batch extract, re-extract many documents), to confirm budget headroom.
The user asks how long the balance will last at the current rate.

When not to use

For per-call cost of a single extraction: that is already on every talonic_extract response under cost.
To top up credits: route the user to the dashboard. Auto top-up is guarded by a separate scope and is intentionally not exposed at the MCP layer.

Response shape

balance_credits: current credit balance (integer).
balance_eur: current balance expressed in EUR (rounded to two decimals).
burn_rate_30d_credits: total credits consumed in the trailing 30 days.
projected_runway_days: days of runway at the current 30-day average burn rate. -1 indicates no consumption in the trailing window (cannot compute a meaningful runway).
tier: API tier of the workspace (free, pro, enterprise, etc.).
tier_resets_at: ISO 8601 timestamp of the next monthly tier reset.

Tool input

{}

Tool response

{
  "balance_credits": 1888,
  "balance_eur": 9.44,
  "burn_rate_30d_credits": 360,
  "projected_runway_days": 157,
  "tier": "pro",
  "tier_resets_at": "2026-06-01T00:00:00.000Z"
}

Example: budget check before batch extraction

Agent checks balance before processing 50 documents

// User: "Extract data from all 50 invoices in my workspace"
// Agent first checks budget:
// talonic_get_balance → {}

// Response:
{
  "balance_credits": 120,
  "balance_eur": 0.60,
  "burn_rate_30d_credits": 360,
  "projected_runway_days": 10,
  "tier": "free",
  "tier_resets_at": "2026-06-01T00:00:00.000Z"
}

// Agent: "You have 120 credits remaining. Extracting 50 documents
//  will cost approximately 50 credits, leaving 70 credits.
//  Your tier resets on June 1st. Shall I proceed?"

Budget-aware agents use talonic_get_balance to prevent unexpected credit depletion. Before starting a large batch extraction, the agent checks the remaining balance and estimates whether the batch will exceed available credits. If the balance is low, the agent can warn the user, suggest processing a subset, or recommend upgrading the plan. This proactive approach prevents mid-batch failures due to exhausted credits.

The tier field indicates the workspace's API plan: free, pro, or enterprise. Each tier has different daily extraction limits and credit allowances. The tier_resets_at timestamp shows when the monthly credit cycle resets, which helps agents answer questions like 'when will my credits refresh?' or 'should I wait for the reset before processing this batch?'. Agents can use this information to advise users on timing large extraction jobs.

The burn_rate_30d_credits field shows total consumption over the trailing 30 days, not a daily average. Agents can divide by 30 to estimate daily usage. Combined with balance_credits, this provides a clear picture of workspace sustainability. A high burn rate with a low balance signals the need for a plan upgrade or reduced usage before the next tier reset.

Frequently asked questions

How do I check my Talonic credit balance from an agent?+

Call talonic_get_balance with no arguments. Returns balance_credits, balance_eur, burn_rate_30d_credits, projected_runway_days, tier, and tier_resets_at. Read-only; safe to call at any time.

What does projected_runway_days = -1 mean?+

It means the workspace has had zero credit consumption in the trailing 30 days, so a meaningful runway projection cannot be computed. Treat -1 as 'unknown' rather than '0 days'.

Should the agent check balance before every extraction?+

Not for single extractions — that would add unnecessary latency. Check the balance before batch operations (10+ documents) or when the user explicitly asks about credits. For single extractions, proceed directly and let the API return a quota error if the balance is exhausted.

How does the agent know the cost of an extraction?+

Each talonic_extract response includes a cost field showing credits consumed for that extraction. Use talonic_get_balance before a batch to check available credits, and after to verify the remaining balance. Single extractions typically cost 1 credit each.

talonic_extract

Pricing