Skip to main content

Credit Usage by Function

See where your credits went: per-function credit consumption (extraction, structuring, intelligence operations) from the customer-pay ledger, 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 customer-pay view: the credits actually charged, 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

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 -X GET "https://api.talonic.ai/v1/usage/credits?days=7" \
  -H "Authorization: Bearer tlnc_your_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.

Related

Pricing Catalog
Credits Balance
Usage Overview