Skip to main content

talonic_get_usage

Returns the workspace's credit consumption grouped by platform function over a trailing window, plus the total. Where talonic_get_balance reports what is left, this tool reports where the credits went: how much each function (page ingestion, structuring cells, intelligence operations) cost over the period. The breakdown is ordered by spend, highest first, so the dominant cost driver is the first row.

When to use

  • The user asks what they have spent credits on, or which function dominates their spend.
  • Reviewing burn by function to decide whether to shift work to batch mode or trim an operation.
  • Producing a spend report for the last N days.

When not to use

  • For the remaining balance and runway: use talonic_get_balance.
  • For per-unit rates before running a job: use talonic_get_pricing.

Arguments

  • days (optional): trailing reporting window in days. Default 30, clamped between 1 and 365.

Response shape

  • period_days: length of the reporting window in days.
  • total_credits: total credits consumed across all functions in the window.
  • by_function: array of { operation_type, operations, credits }, highest spend first.
Tool input
{ "days": 30 }
Tool response
{
  "period_days": 30,
  "total_credits": 48200,
  "by_function": [
    { "operation_type": "page_ingest", "operations": 412, "credits": 41200 },
    { "operation_type": "structuring_cell", "operations": 300, "credits": 6000 },
    { "operation_type": "intelligence_op", "operations": 10, "credits": 1000 }
  ]
}

Agents use talonic_get_usage to attribute spend to the functions that caused it. Pairing it with talonic_get_balance gives a full picture: balance shows how much is left, usage shows what consumed it, and pricing shows the rate of each function. An agent noticing that page ingestion dominates spend might suggest batch mode for the 0.5x discount, or reusing schemas so more cells resolve from the Field Registry for free.

The figures read from the credit transaction ledger, so they reconcile exactly with the balance and history reported elsewhere. The operation_type values match the unit identifiers in the pricing catalog, which lets an agent join usage to rates and explain not just how many credits a function consumed but why. To express any figure in euros, divide by the credits-per-EUR rate from the pricing catalog.

Frequently asked questions

How is talonic_get_usage different from talonic_get_balance?+
Balance reports what is left (and runway); usage reports what was spent, grouped by function. Use balance to check headroom and usage to attribute spend to extraction, structuring, or intelligence operations.
What window does talonic_get_usage cover?+
The last 30 days by default. Pass days to change it, anywhere from 1 to 365. The response echoes period_days so the agent can confirm the window it summarized.
Why is the breakdown empty?+
Per-function rows populate as billable operations are charged. While metering runs in shadow mode the ledger records what each operation would cost without deducting, so the breakdown can be empty until enforcement is enabled. Pricing still returns the rates in the meantime.

Related

talonic_get_pricing
talonic_get_balance