Usage & Monitoring

Usage & Monitoring

SpecGraph gives you full visibility into how your organization's token budget is being used — from a real-time balance widget in the sidebar to a detailed per-action breakdown in Settings.

Sidebar Balance Widget

The left sidebar shows a compact token balance indicator at the bottom of the navigation:

• Green bar — healthy balance (under 70% consumed)
• Amber bar — getting low (70–90% consumed)
• Red bar — critically low (over 90% consumed)

The widget shows remaining SGT out of your monthly allocation at a glance. Click it to go directly to Settings → Billing.

Settings → Billing Page

The full billing page (/settings/billing) shows:

Current Plan Card

• Plan name and tier (Starter / Professional / Enterprise)
• Subscription status (Active / Trialing / Past Due / Cancelled)
• Billing period start and end dates

Token Balance

• Allocated — total SGT for this billing period
• Consumed — total SGT used so far
• Reserved — SGT held for in-flight AI actions (not yet settled)
• Remaining — allocated - consumed - reserved
• Visual progress bar with color coding (green / amber / red)

Transaction History

A paginated log of every token transaction for your organization, including:

Admin View — Per-Organization

System admins can view any organization's usage from Admin → Organizations → [org name] → Usage tab:

Usage by Action Table

Shows aggregate consumption broken down by action type:

Sorted by total consumption descending — the heaviest actions appear first.

Recent Transactions Table

Last 50 token transactions for the organization. Same columns as the user-facing history, but visible to admins across all projects and users.

Subscription Tab

Admins can see the full subscription detail:

• Current plan, tier badge, and status
• Token balance grid (allocated / consumed / remaining)
• Usage progress bar
• Period start and end dates
• Action buttons: Topup Tokens, Change Plan, Cancel or Reactivate

Topups

A topup adds a one-time SGT credit to an organization's balance outside the regular monthly allocation. Only system admins can perform topups.

How to Topup

1. Go to Admin → Organizations → [org name] → Subscription tab
2. Click Topup Tokens
3. Enter the amount (SGT) and an optional description (e.g. "Q1 bonus allocation")
4. Click Topup — balance updates immediately

Alternatively, from Admin → Subscriptions, click the ⋯ menu on any organization row and select Topup Tokens.

Topup vs. Plan Change

Billing Cycle

• The billing cycle runs month to month
• Tokens reset on the 1st of each month at midnight UTC
• Unused tokens do not carry over — each cycle starts fresh from the plan allocation
• If a topup was performed mid-cycle, those tokens are also cleared on reset

Monthly Reset Process

On the 1st of each month, for each organization with an active subscription:

1. Token balance resets to the monthly plan allocation
2. Any stale in-flight reservations (older than 24 hours) are released
3. The reset is logged as a credit transaction with description "Monthly allocation reset"

Organizations with a cancelled subscription receive no allocation on reset — balance stays at 0.

Usage Thresholds & Alerts

When blocked, users see the specific action's estimated cost alongside the remaining balance — making it clear exactly how far over budget the action would be.

Audit Trail

Every token movement is permanently logged and cannot be edited or deleted. The audit trail records:

• Timestamp
• Organization, Project, and User IDs
• Action type
• Foundation cost (SGT)
• LLM input tokens, output tokens, and total
• AI cost (SGT)
• Total cost (SGT)
• LLM provider and model used (e.g. google / gemini-2.0-flash)

This provides full accountability for every SGT spent, useful for internal cost allocation or external reporting.