Skip to main content

Usage Summary

Get an aggregate usage summary grouped by operation type and AI model, with call counts, token totals, and cost estimates, via GET /v1/credits/usage.

The usage summary endpoint (GET /v1/credits/usage) returns a high-level view of your API usage grouped by operation type and model. It aggregates call counts, token consumption, and estimated USD costs over a configurable lookback period, so you can see at a glance which operations drive your spending.

Call this endpoint to build cost dashboards or to identify which pipeline operations consume the most credits. The default lookback is 30 days — pass the days query parameter to adjust. Each row in the stats array represents a unique combination of operation_type and model.

The response includes call_count, total_input_tokens, total_output_tokens, total_cache_read_tokens, and total_cost_usd per grouping. Note that token-based operations (e.g. extraction via Claude) report full token breakdowns, while page-based operations (e.g. document_ai_ocr) report zero tokens since cost is calculated from pages processed.

Pair with Daily Usage for time-series analysis of the same period, or with Usage Log to drill into individual requests behind a high-cost grouping. The period_days field in the response confirms the actual lookback window applied.

Cost estimates include all token classes: input tokens, output tokens, cache creation tokens, and cache read tokens. Each is priced at the model-specific rate.
GET/v1/credits/usage

Query parameters

daysintegerNumber of days to look back (default 30).

cURL — Usage summary for the last 7 days

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

Response

Response fields

statsarrayArray of usage stat rows grouped by operation_type and model.
stats[].operation_typestringOperation category (e.g. extraction, matching, document_ai_ocr).
stats[].modelstringModel used for this operation.
stats[].call_countintegerNumber of calls.
stats[].total_input_tokensintegerTotal input tokens consumed.
stats[].total_output_tokensintegerTotal output tokens produced.
stats[].total_cache_read_tokensintegerTotal cache-read tokens (prompt cache hits).
stats[].total_cost_usdnumberEstimated total cost in USD.
period_daysintegerThe period covered by this summary in days.

Response

{
  "stats": [
    {
      "operation_type": "extraction",
      "model": "claude-sonnet",
      "call_count": 1842,
      "total_input_tokens": 7896420,
      "total_output_tokens": 1127040,
      "total_cache_read_tokens": 0,
      "total_cost_usd": 40.57
    },
    {
      "operation_type": "document_ai_ocr",
      "model": "mistral-ocr",
      "call_count": 920,
      "total_input_tokens": 0,
      "total_output_tokens": 0,
      "total_cache_read_tokens": 0,
      "total_cost_usd": 8.28
    }
  ],
  "period_days": 30
}

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

Why does document_ai_ocr show zero tokens?+
Document AI OCR (Mistral) is not token-based. Its cost is calculated from `pages_processed * cost_per_page`. Token fields are 0 because they do not apply to this operation type.
Can I change the lookback period?+
Yes. Pass the `days` query parameter to set the lookback window. The default is 30 days. There is no maximum limit.
What is the difference between the usage summary and the usage log?+
The summary (`GET /v1/credits/usage`) returns one aggregated row per operation type and model, which is efficient for dashboards. The log (`GET /v1/credits/usage/log`) returns every individual request with its own token counts and cost, which is what you need for auditing or tracing a specific expensive call.

Related

Daily Usage
Usage Log
Credit Usage by Function