Skip to main content

Analytics and exports

Analytics endpoints use an authenticated dashboard session. Filter by range and group usage by plan, feature, or customer.

Usagey analytics workspace showing date, grouping, customer, feature, and plan filters
The analytics workspace keeps the chart, ranked results, and CSV export aligned to the same active filters.
const response = await fetch(
  'https://usagey.com/api/billing/analytics?organizationId=org_123&env=sandbox&range=30d&groupBy=plan',
  {credentials: 'include'},
);

const analytics = await response.json();
console.log(analytics.totals.revenueTotals);

Revenue-bearing responses expose revenueTotals or currencyTotals arrays. Revenue includes succeeded charges and completed refunds; pending refunds do not reduce recognized totals.

Internal commercial evidence​

Platform administrators can request a rolling economics report from /api/admin/economics/evidence. The default window is three finalized periods. The report uses quantity-weighted paid-account totals rather than averaging account ratios, and exposes Free-tier usage and variable cost separately.

Economics snapshots and cost inputs run inside audited commercial-control-plane transactions. Organization-owned economics records are isolated by PostgreSQL RLS, while global infrastructure cost inputs are unavailable to ordinary workspace contexts.

The report's pricingBasis is always FULLY_LOADED_COST_PER_THOUSAND. Its pricing rate floor is derived from fixed, variable, and direct allocated cost at the requested gross-margin target; marginal cost is diagnostic only and is never used for rate guidance.

Accounts that reach 100% of allowance in consecutive periods appear in growthSignals from the second consecutive period. This is an internal upgrade or Enterprise qualification signal, not an automatic plan change or customer outreach action.

Quota rollout control​

The organization Usage tab in platform administration compares account counters with immutable consuming meter events. Enforcement cannot be enabled while the report contains missing counters, counter mismatches, orphan events, overlapping periods, or truncated evidence.

Every shadow-to-enforced change and rollback is append-only application history containing the platform administrator, reason, evidence window, generated timestamp, and reconciliation summary. Enforcement is organization-specific; organizations without an explicit decision continue using the environment fallback.

Export​

const response = await fetch(
  'https://usagey.com/api/billing/analytics/export?organizationId=org_123&env=sandbox&range=30d&dataset=overview&format=json',
  {credentials: 'include'},
);

const rows = await response.json();
console.log(rows[0].currencyTotals?.netRevenue);