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