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

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.

Related

Daily Usage
Usage Log
Credit Usage by Function