Cost Governance

Arbitex tracks token consumption on every request through the audit trail. Cost governance turns that telemetry into actionable FinOps controls: per-org, per-team, and per-project cost attribution, configurable provider cost tables, and budget enforcement with soft warnings and hard caps.

No additional telemetry collection is required — cost governance builds on existing audit data fields: org_id, user_id, provider, model, token_count_input, token_count_output, and cost_estimate.

---

Token cost attribution

Every AI request through the platform records token counts and an estimated cost. Cost attribution aggregates this data across multiple dimensions.

Cost attribution API

Query cost data with dimension and time-range filters:

# Per-user attribution for the current month
curl "https://your-platform/api/usage/attribution?group_by=user&date_from=2026-03-01" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

[
  {
    "group_key": "user",
    "group_value": "[email protected]",
    "input_tokens": 8234102,
    "output_tokens": 2103847,
    "total_cost": 2847.21,
    "request_count": 4521
  },
  {
    "group_key": "user",
    "group_value": "[email protected]",
    "input_tokens": 1503221,
    "output_tokens": 1006222,
    "total_cost": 1976.26,
    "request_count": 2103
  }
]

Grouping dimensions

group_by	Description	Sort order
user	Per-user spend	By total cost descending
model	Per-model spend	By total cost descending
day	Daily spend totals	By date ascending

Additional filters: user_id, model_id, date_from, date_to.

Usage summary

Get the current period overview:

curl "https://your-platform/api/v1/admin/usage/summary" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns request count, input/output tokens, cost estimate, plan limit, warning level (none, warning_80, warning_95), and period boundaries.

Per-model breakdown

curl "https://your-platform/api/v1/admin/usage/by-model" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns aggregated request count, input tokens, output tokens, and cost estimate per model across rollup data.

Usage history

Cursor-paginated rollup data with configurable granularity:

curl "https://your-platform/api/v1/admin/usage/history?granularity=daily&limit=30" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Supported granularity: hourly, daily, monthly.

---

Provider cost table

Token prices vary by provider and model and change over time. Arbitex uses an admin-configurable cost rate table rather than hardcoded prices. Rates are specified in USD per 1,000 tokens.

Viewing the cost table

The cost rate table is stored in the system_config table under the key cost_rates:

curl https://your-platform/api/v1/admin/config/cost_rates \
  -H "Authorization: Bearer $ADMIN_TOKEN"

{
  "cost_rates": {
    "claude-sonnet-4-6": {
      "input_per_1k": 0.003,
      "output_per_1k": 0.015
    },
    "gpt-4o": {
      "input_per_1k": 0.005,
      "output_per_1k": 0.015
    },
    "gpt-4o-mini": {
      "input_per_1k": 0.00015,
      "output_per_1k": 0.0006
    }
  }
}

Rate resolution order

The platform resolves cost rates with the following priority:

1. In-memory overrides (runtime API)
2. cost_rates key in system_config table (database)
3. ARBITEX_COST_RATES environment variable (JSON string)
4. Default zero rates

Updating the cost table

Update prices when providers change their rates:

curl -X PUT https://your-platform/api/v1/admin/config/cost_rates \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "claude-sonnet-4-6": {
        "input_per_1k": 0.003,
        "output_per_1k": 0.015
      }
    }
  }'

The table is editable at runtime without restart. Cost estimates on audit events are computed using the active cost table at request time.

Note

If a model is not in the cost table, the platform logs the request with zero cost estimate. Add new models to the table when you configure them as providers.

Cost routing tiers

Models can be organized into cost tiers for cost-aware routing:

Endpoint	Method	Description
/api/v1/admin/cost-routing/tiers	GET	List all model tier assignments
/api/v1/admin/cost-routing/tiers/names	GET	List tier names
/api/v1/admin/cost-routing/tiers/{tier}/weights	PUT	Update per-model weights in a tier
/api/v1/admin/cost-routing/tiers/assign	POST	Assign a model to a tier with cost rates
/api/v1/admin/cost-routing/tiers/assign/bulk	POST	Bulk assign models to tiers
/api/v1/admin/cost-routing/select	POST	Preview cheapest model selection for a tier

---

Budget enforcement

Budget limits are configured per user and per group using the quota system. Each quota record can set daily and monthly limits for tokens, requests, and USD spend.

Quota configuration

Quota field	Scope	Description
daily_token_limit	Per-user or per-group	Maximum tokens per day
monthly_token_limit	Per-user or per-group	Maximum tokens per month
daily_request_limit	Per-user or per-group	Maximum requests per day
monthly_request_limit	Per-user or per-group	Maximum requests per month
daily_cost_limit_usd	Per-user or per-group	Maximum USD spend per day
monthly_cost_limit_usd	Per-user or per-group	Maximum USD spend per month

A null value means unlimited for that field.

Hard cap (blocking)

When a user’s accumulated spend reaches or exceeds their monthly_cost_limit_usd, the platform raises a BudgetLimitExceededError and blocks the request. The error response includes the budget limit, current spend, and a retry_after timestamp (first of the next month).

Hard cap checks run inline in the request pipeline — every request is checked before being forwarded to the model provider.

Soft cap (warning)

The BudgetProjectionService monitors budget utilization and generates warnings at configurable thresholds (default: 50%, 75%, 90%). Warnings are also generated when the projected exhaustion date is within a configurable proximity (default: 5 days).

Burn rate is calculated as a rolling 7-day average from usage records. Projected monthly total = daily_burn_rate * days_in_month.

Budget alerts

Usage alerts are accessible via the admin API:

curl "https://your-platform/api/v1/admin/usage/alerts" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns paginated UsageAlert records with alert type, message, and trigger timestamp.

---

Cost dashboard

The Cloud portal provides cost visibility at Admin > Cost Management with:

• Usage summary: current period request count, token totals, cost estimate, and warning level
• Model breakdown: cost per model with token count details
• Usage history: daily/hourly/monthly trend charts
• Budget status: spend against configured limits with warning indicators
• Cost forecast: projected monthly total, burn rate, exhaustion date, and trend direction

Cost forecast API

curl "https://your-platform/api/v1/admin/cost/forecast" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

{
  "daily_burn_rate": 156.78,
  "projected_monthly_total": 4860.18,
  "projected_exhaustion_date": "2026-04-22",
  "trend": "increasing",
  "confidence_interval": {
    "low": 4102.50,
    "high": 5617.86
  }
}

Optional filters: user_id, group_id.

---

Related

• Quota Management — per-group usage limits (rate-based and cost-based)
• Audit Log Management — audit data that powers cost attribution
• Policy Engine — rule evaluation model and action types