Usage Tracking

Usage tracking is the core runtime integration in spendware. A usage event can come from a provider adapter, a direct SDK call, or a raw API request.

Preflight And Logging

Preflight checks run before a provider call. They can enforce policies such as usage thresholds, allowed providers, or customer/project context requirements.

Usage logging runs after a provider call or after your service computes usage. It records request counts, input tokens, output tokens, cached tokens, provider/model metadata, customer/project context, and optional error details. Provider adapters extract and normalize cached token metrics into a separate cached_tokens field, treated as a mutually exclusive token category. total_tokens is the sum of input_tokens, output_tokens, and cached_tokens.

SDK configuration supports strict, best-effort, disabled, and dry-run behavior depending on how you want runtime failures to affect provider calls.

Runtime Keys

Use customer keys for runtime traffic. The least-privilege scopes are:

• preflight:read for preflight checks.
• usage:write for usage logging.

Use user API keys for management automation only. Do not ship management keys inside provider-adapter runtime services.

Raw Counts And Presentation Units

Write-side usage uses raw token and request counts. Keep preflight payloads, usage logging payloads, guardrail thresholds, billing math, and stored counts in raw units.

Read APIs can scale totals for presentation with token_unit_size and request_unit_size. Supported values are hundred, thousand, million, and billion. Monetary fields, IDs, dates, and metadata do not change when presentation units are supplied.

Analytics Behavior

Spendware returns finalized usage by default so analytics, billing, and guardrails align on resolved projects, customers, and providers. Some import workflows can also include eligible unresolved partial usage when you request it explicitly.

If a query does not return what you expect, check the date window, project/customer filters, partial usage mode, and whether the usage has been finalized.

Runtime Context

Runtime context tells Spendware which customer, project, feature, or external IDs should receive a provider call's usage. In multi-tenant services, prefer a resolver or per-call override instead of one global customer context.

Historical And Partial Usage

The management SDK exposes direct usage and partial usage logging workflows for cases where usage is imported or finalized later. Use these paths carefully, keep external IDs stable, and keep timestamps explicit when importing historical activity.