Budget & Usage

Endpoints for tracking AI costs, budget limits, and usage analytics.

GET /api/ai-budget

Get the current user's AI budget status.

Authentication: Required (session with AI seat)

Pre-blocks: ai.verify

Response:

{
  "username": "alice",
  "plan": {
    "id": "advanced-456",
    "name": "Advanced AI",
    "slug": "advanced",
    "tier": "advanced",
    "weeklyBudget": 2.00,
    "sessionBudget": 0.40
  },
  "weekly": {
    "budget": 2.00,
    "used": 1.23,
    "remaining": 0.77,
    "periodStart": "2024-01-10T09:00:00Z",
    "periodEnd": "2024-01-17T09:00:00Z",
    "resetIn": "1d 18h 42m"
  },
  "session": {
    "budget": 0.40,
    "used": 0.15,
    "remaining": 0.25,
    "periodStart": "2024-01-15T12:00:00Z",
    "periodEnd": "2024-01-15T18:00:00Z",
    "resetIn": "3h 18m"
  },
  "boost": {
    "budget": 5.00,
    "used": 0.75,
    "remaining": 4.25,
    "expiresAt": "2024-02-10T09:00:00Z"
  },
  "totalRemaining": 5.02,
  "estimatedTurns": {
    "everyday": 250,
    "advanced": 50,
    "strategic": 10
  }
}

Budget Fields:

Field	Type	Description
plan	object	Current AI plan details
weekly	object	Weekly budget cycle (7 days from seat assignment)
session	object	Session budget (6-hour rolling window)
boost	object	One-time boost budget (admin-granted)
totalRemaining	number	Sum of all remaining budgets (USD)
estimatedTurns	object	Approximate turns remaining by tier

Budget Enforcement:

• Weekly budget resets 7 days after seat assignment
• Session budget resets every 6 hours from first usage
• Boost budget is consumed first, then weekly/session
• Requests exceeding remaining budget return 403 Forbidden

Estimated Turns:

Calculated using typical costs per tier:

• Everyday: ~$0.002 per turn (500 turns per $1)
• Advanced: ~$0.020 per turn (50 turns per $1)
• Strategic: ~$0.100 per turn (10 turns per $1)

Budget Planning

Weekly and session budgets prevent excessive costs. Monitor estimatedTurns to help users understand their remaining capacity before hitting limits.

---

GET /api/ai-usage

Get monthly AI usage statistics.

Authentication: permission.tenant.superuser

Query Parameters:

Parameter	Type	Default	Description
month	string	Current month	ISO date (YYYY-MM-DD) for month to query

Example Request:

GET /api/ai-usage?month=2024-01

Response:

{
  "month": "2024-01",
  "summary": {
    "totalCost": 248.67,
    "totalRequests": 12450,
    "averageCostPerRequest": 0.02,
    "uniqueUsers": 28,
    "topUsers": [
      {
        "username": "alice",
        "displayName": "Alice Smith",
        "cost": 32.45,
        "requests": 1620,
        "plan": "Advanced AI"
      },
      {
        "username": "bob",
        "displayName": "Bob Jones",
        "cost": 28.90,
        "requests": 1445,
        "plan": "Strategic AI"
      }
    ]
  },
  "byPlan": [
    {
      "planId": "advanced-456",
      "planName": "Advanced AI",
      "planSlug": "advanced",
      "cost": 156.23,
      "requests": 7811,
      "users": 18
    },
    {
      "planId": "strategic-789",
      "planName": "Strategic AI",
      "planSlug": "strategic",
      "cost": 78.44,
      "requests": 784,
      "users": 5
    }
  ],
  "byModel": [
    {
      "modelId": "claude-3-5-sonnet",
      "modelName": "Claude 3.5 Sonnet",
      "tier": "advanced",
      "cost": 134.56,
      "requests": 6728,
      "promptTokens": 4500000,
      "completionTokens": 1200000
    }
  ],
  "byDay": [
    {
      "date": "2024-01-01",
      "cost": 7.89,
      "requests": 394
    },
    {
      "date": "2024-01-02",
      "cost": 8.45,
      "requests": 422
    }
  ],
  "budgetUsage": {
    "weeklyBudgetAllocated": 70.00,
    "weeklyBudgetUsed": 52.34,
    "weeklyBudgetRemaining": 17.66,
    "sessionBudgetAllocated": 14.00,
    "boostBudgetGranted": 25.00,
    "boostBudgetUsed": 3.45
  }
}

Usage Breakdown:

Section	Description
summary	Overall costs and top users
byPlan	Costs grouped by AI plan
byModel	Costs grouped by model
byDay	Daily cost trend
budgetUsage	Budget allocation and consumption

Metrics:

• totalCost: All AI costs for the month (USD)
• totalRequests: Count of chat/completion requests
• averageCostPerRequest: Mean cost per request
• uniqueUsers: Active users with AI seats
• promptTokens: Input tokens consumed
• completionTokens: Output tokens generated

---

GET /api/ai-overview

Get admin dashboard metrics for AI usage and entitlements.

Authentication: permission.tenant.superuser

Response:

{
  "entitlements": {
    "totalSeats": 35,
    "assignedSeats": 28,
    "unassignedSeats": 7,
    "enterpriseSeats": 0,
    "plans": [
      {
        "id": "everyday-123",
        "name": "Everyday AI",
        "slug": "everyday",
        "seats": 15,
        "assigned": 12
      },
      {
        "id": "advanced-456",
        "name": "Advanced AI",
        "slug": "advanced",
        "seats": 15,
        "assigned": 13
      },
      {
        "id": "strategic-789",
        "name": "Strategic AI",
        "slug": "strategic",
        "seats": 5,
        "assigned": 3
      }
    ]
  },
  "usage": {
    "today": {
      "cost": 8.45,
      "requests": 422,
      "activeUsers": 18
    },
    "week": {
      "cost": 52.34,
      "requests": 2617,
      "activeUsers": 24
    },
    "month": {
      "cost": 248.67,
      "requests": 12450,
      "activeUsers": 28
    }
  },
  "budget": {
    "weeklyAllocated": 70.00,
    "weeklyUsed": 52.34,
    "weeklyRemaining": 17.66,
    "percentUsed": 74.77,
    "boostGranted": 25.00,
    "boostUsed": 3.45,
    "boostRemaining": 21.55
  },
  "trends": {
    "costVsPreviousMonth": 12.5,
    "requestsVsPreviousMonth": 8.3,
    "averageCostPerUser": 8.88,
    "topModels": [
      {
        "modelId": "claude-3-5-sonnet",
        "modelName": "Claude 3.5 Sonnet",
        "cost": 134.56,
        "requests": 6728
      }
    ]
  },
  "alerts": [
    {
      "type": "budget_warning",
      "severity": "medium",
      "message": "Weekly budget 75% consumed",
      "value": 74.77
    }
  ]
}

Dashboard Sections:

Section	Description
entitlements	Seat allocation across plans
usage	Cost and request metrics by period
budget	Budget consumption and remaining
trends	Month-over-month comparisons
alerts	Warnings and notifications

Alert Types:

• budget_warning - Budget threshold exceeded (75%, 90%, 100%)
• seat_shortage - Few unassigned seats remaining
• cost_spike - Unusual cost increase detected
• model_deprecation - Model approaching deprecation

Use Cases:

• Executive dashboard display
• Cost monitoring and alerting
• Capacity planning
• User activity tracking

Refresh Rate

Dashboard metrics are calculated on-demand. For high-traffic tenants, consider caching responses client-side for 5-15 minutes.

---

Usage Tracking Implementation

Cost Calculation:

Costs are calculated using model pricing per million tokens (PPM):

cost = (promptTokens / 1000000 * promptPpm) +
       (completionTokens / 1000000 * completionPpm) +
       (cacheReadTokens / 1000000 * cacheReadPpm) +
       (cacheWriteShortTokens / 1000000 * cacheWriteShortPpm) +
       (cacheWriteLongTokens / 1000000 * cacheWriteLongPpm)

Budget Enforcement:

Before processing a request:

1. Check boost budget (consumed first)
2. Check session budget (6-hour window)
3. Check weekly budget (7-day cycle)
4. If all budgets exhausted, return 403 Forbidden

After processing:

1. Deduct cost from boost budget first
2. Deduct remaining from session budget
3. Deduct remaining from weekly budget
4. Record transaction for reporting

Period Management:

• Weekly period starts at seat assignment, resets every 7 days
• Session period starts at first usage, resets every 6 hours
• Boost period starts at grant time, expires after 30 days

Token Counting:

Tokens are counted by the AI provider and returned in response metadata. Informer records:

• promptTokens - Input tokens
• completionTokens - Output tokens
• cacheReadTokens - Tokens read from prompt cache
• cacheWriteShortTokens - Short-term cache writes (5 minutes)
• cacheWriteLongTokens - Long-term cache writes (persistent)

Cost Accuracy

Token counts and costs are estimated for streaming responses and finalized after completion. UI should display estimated costs during streaming and final costs after completion.