Skip to content

Reading Results

Dhanush edited this page Oct 23, 2026 · 1 revision

Reading Results

Client::fetch returns a UsageSnapshot. Its fields describe what the provider actually reported, normalized into common types.

Field Meaning
provider, scope The selected provider and account routing
source, credential_source Delivery path and whether credentials came from the caller or opt-in local access
fetched_at UTC observation time
windows Quota or allowance windows, sometimes with a model or group label
balances Available money or provider-specific credits
spend Provider-reported billed or account spend for a named period
warnings Nonfatal missing or malformed optional data

Quota windows

A QuotaWindow can include used, remaining, a QuotaLimit, utilization_percent, duration_seconds, resets_at, kind, unit, and an optional model. Values are optional because providers report different surfaces. Known, Unknown, and Unlimited limits are distinct. A missing limit or reset remains missing; agentstat does not invent an allowance from a percentage.

Five-hour and weekly windows measure quota consumption over those periods, not hours actively spent coding. A model label identifies a provider-reported model or group. No label does not imply a per-model breakdown.

Money and credits

Amounts use exact Decimal values and serialize as strings. Keep Unit::Currency("USD") separate from provider credit units. A USD-equivalent quota allowance is not automatically billed spend. Valid overages and negative prepaid balances are preserved where the provider reports them.

Multiple accounts

Reuse a Client for connection pooling. fetch_many keeps input order and returns one Result per request; one account's failure does not erase another account's result. The default concurrency is four fetches. Your application decides when to poll, cache, store, and render the data.

Transport and limits

The default whole-fetch deadline is 30 seconds and the HTTP response limit is 2 MiB. There are no automatic retries, redirects, background requests, or token refreshes. The library omits remote response bodies and credentials from errors. Custom HTTP executors and endpoint overrides are available for explicit integrations; see the source usage guide.

For failure meanings and next steps, see Troubleshooting.

Clone this wiki locally