Skip to main content

Credit Usage by Function

See where your credits went: per-function credit consumption across extraction, structuring, and intelligence operations over a trailing window.

The Credit Usage endpoint reports how many credits the workspace spent on each platform function over a trailing window. Where the aggregate Usage endpoint reports raw AI token counts, this endpoint reports the billing view: the credits actually charged to your organization, grouped by the function that incurred them. It answers "where did my credits go" rather than "how many tokens did the platform burn".

Consumption is grouped by operation_type, the billable function (for example page ingestion, structuring cells, or intelligence operations such as matching and reconciliation). Each group reports the number of charged operations and the total credits they consumed, and the response carries a workspace total across all functions. The breakdown is ordered by spend, highest first, so the dominant cost driver is the first row.

The window defaults to the last 30 days and is configurable from 1 to 365 days through the days query parameter. The endpoint reads the credit transaction ledger directly, so the figures reconcile exactly with the balance and transaction history reported by the Credits API. To convert credits to euros, divide by the credits-per-EUR rate returned by the Pricing API (1,000 credits per EUR at the standard rate).

This endpoint requires an API key with the read scope. It is the natural companion to the Credits Balance endpoint: balance answers "how much is left", and credit usage answers "what consumed it". Together they let an agent monitor burn by function and decide whether to shift work to batch mode or trim a particular operation.

Per-function rows populate as billable operations are charged. While credit metering runs in shadow mode the ledger records what each operation would cost without deducting, so the breakdown can legitimately read as empty until enforcement is enabled for the workspace.
GET/v1/usage/credits

Query parameters

daysintegerTrailing reporting window in days. Default 30, clamped between 1 and 365.

Response

Response fields

period_daysintegerLength of the reporting window in days.
total_creditsintegerTotal credits consumed across all functions in the window.
by_functionarrayPer-function breakdown, highest spend first.
by_function[].operation_typestringThe platform function (billable operation type) that consumed credits.
by_function[].operationsintegerNumber of charged operations of this type in the window.
by_function[].creditsintegerTotal credits consumed by this function.

Response — Credit usage by function

{
  "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 }
  ]
}

cURL — Credit usage for the last 7 days

curl "https://api.talonic.com/v1/usage/credits?days=7" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Errors

Error responses

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

Frequently asked questions

How is this different from the aggregate Usage endpoint?+
The aggregate Usage endpoint reports raw AI token and call counts (the technical view). Credit Usage reports the credits actually charged to your organization per function from its credit ledger (the billing view). One tells you token cost; the other tells you where your credits went.
What does operation_type contain?+
It is the billable function that consumed the credits, such as page_ingest for document ingestion, structuring_cell for cells filled by model reasoning, or intelligence_op for matching, cases, and reconciliation. The values match the unit identifiers in the Pricing catalog.
Why is my breakdown empty?+
Per-function rows appear once 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. The Pricing endpoint still returns the rates in the meantime.
How do I convert credits to euros?+
Divide credits by the credits_per_eur value returned by the Pricing endpoint (1,000 credits per EUR at the standard rate). For example, 41,200 credits of page ingestion is 41.20 EUR.

Related

Pricing Catalog
Credits Balance
Usage Overview