Usage API

GET /v1/usage is the Console's canonical usage, spend, and earnings response. It is operator-scoped and uses UTC windows.

curl "https://api.getstack.run/v1/usage?since=2026-08-01T00:00:00Z&until=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer $STACK_TOKEN"

Consumption

• consumption.activity.total counts every audit event only when total_coverage is complete. Partial coverage makes the total a lower bound.
• consumption.activity.total_coverage states whether the activity total is complete or partial.
• consumption.actions counts only actions charged against the monthly action allowance.
• allowance_coverage states whether the historical month has a durable tier snapshot.
• detail_coverage states whether by_kind is complete, partial, or unavailable.
• Legacy passports, proxy_calls, dropoffs, and skill_invocations fields have limit: null. They are breakdowns, not separate quotas.
• For a white-label partner or one of its tenants, the action allowance is shared. consumption.actions.used is the pool total, own_used is the caller's share, pooled is true, and tenants counts the tenants in the pool. Plan, allowances, and pass-through counters are the partner's.

A non-GET proxy write is counted once when STACK admits the durable operation. Unchanged retries use the same operation and do not add another action. Operation-status and stored-response reads are unmetered. A proxy request refused after policy evaluation still consumes an attempt. LLM gateway calls remain separate actions and do not inherit the proxy write-recovery contract.

Seats, allowances, and inventory

Seats include the owner. A billing-period response reports current-month pass-through allowances for L3 classifications, SMS, and email. A custom time window returns passthrough: null because the historical counters are not durable. Agents, service connections, published skills, and inbound webhook endpoints are current point-in-time counts under unlimited. For a custom window, agent and published-skill rows also include created_in_window. Fair-use egress and agent-registration ceilings are published separately.

Money

spend_cents reports actual STACK wallet spend by bucket. Top-ups, refunds, and adjustments are wallet movements, not product spend. LLM provider costs remain separate from STACK fees and wallet debits. The response also includes wallet balance and unpaid and lifetime publisher earnings.