statshawk
ReferenceData modelShared primitives

AccountUsage

Current-period quota snapshot for the authenticated account.

object
analysis_unlockedbooleanrequired

Whether paid analysis routes are allowed for this account's effective tier.

configured_tierstringnulloptional

The plan the account is configured for when `reason` is `billing_incomplete`; `tier` still reports the effective `free`.

period_resetstringrequired

Inclusive-exclusive period end (`period_end`) as RFC 3339.

reasonstringnulloptional

`billing_incomplete` when this is a paid-tier row that fail-closed to `free` for lack of billing linkage (`AccountContext::degraded_from`). Absent for genuinely free and for fully-linked accounts, so those payloads are byte-for-byte unchanged. Same marker BillingLayer puts in `TIER_REQUIRES_PAID` data: the fix is billing setup, not an upgrade.

tierstringrequired

Effective plan slug (`free`, `hobby`, `pro`, …).

units_limitinteger<int64>required

Effective hard cap / included units for the period.

units_remaininginteger<int64>required

`max(0, units_limit - units_used - units_reserved)` — same headroom `reserve_atomic` enforces. `units_used` stays finalized-only.

units_usedinteger<int64>required

Finalized units consumed in the current billing period.

upgrade_urlstringrequired

Always `https://app.statshawk.ai/billing` — required on every success payload, not only near-cap. Same constant BillingLayer uses for `TIER_REQUIRES_PAID` / `QUOTA_EXCEEDED`. MCP prefers this over marketing `/pricing` for logged-in accounts.

Used by