Skip to main content

Usage Summary

Get aggregate credit usage summary broken down by operation type and model for a configurable time period.

Get a high-level view of your API usage grouped by operation type and model. This endpoint aggregates call counts, token consumption, and estimated costs over a configurable lookback period. Use it to understand 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

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