Budgets

A budget is a dollar limit on spend through ACOG for a period. When a budget is used up, ACOG pauses new requests that count against it until the period resets.

Scopes and windows

Scope	Pool	Counts
Organization	One pool for the whole organization	All spend
Team	One pool shared by the team’s members	Spend by the team’s members
Person	That person’s own pool	Spend with the person’s keys

Window	Resets
Daily	Midnight UTC
Weekly	Every seven days, at midnight UTC on Thursday
Monthly	The first of the month, midnight UTC

Every budget that applies to a request is checked, and the tightest one decides. A person on several teams with budgets counts against exactly one of them: the team with the highest limit.

Spend is the actual cost of each request (see How savings are measured), so savings stretch a budget.

Setting budgets

Open Admin → Governance → Spending & limits → Budgets. Viewing budgets requires the View invoices and billing status permission; creating and changing them requires Set spend budgets, rate limits, model access, and guardrails (admin:budgets). Each row expands to show live usage, warnings already sent, the reset time and, for a team, spend per member.

With the API:

curl -s -X PUT https://acog.tessarac.com/api/v1/orgs/$ORG_ID/budgets/group/$TEAM_ID \
  -H "Authorization: Bearer $ACOG_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": 500, "window": "week"}'

The scope in the path is org, group (a team) or user. There is no “unlimited” value: delete the budget instead.

Warnings in responses

When a budget that applies to a request passes 50, 80 or 90% of its limit, ACOG warns in the response itself, once per threshold per period:

• A one-line notice is appended after the model’s reply, in the form ⚠ Budget notice: this {organization|group|personal} {daily|weekly|monthly} budget is {pct}% consumed (${used} of ${limit}). In a stream, it arrives as a final text event. Token usage figures are not changed.
• The response header x-acog-budget-notice carries the same information for programs, for example group/week=80.

Warnings apply to chat and message responses, not to embeddings.

When a budget is used up

When a budget reaches 100% of its limit, requests that count against it are refused until the window resets:

{
  "error": {
    "type": "budget_exhausted",
    "message": "…",
    "scope": "group",
    "window": "week",
    "decision_id": "…"
  }
}

The status is 402. scope is org, group or user: the most specific budget that ran out.

Alerts

The webhook events budget.threshold_crossed (when a budget passes 50, 80 or 90% of its limit) and budget.exhausted (when it reaches 100% of its limit) carry the scope, window, percentage, amount used and limit.

Your organization’s maximum

On the hosted service your plan may also set a ceiling over all of your traffic, shown at the top of Spending & limits. No budget you set can exceed it. Contact us to raise it.

If budgets cannot be checked

If ACOG cannot read budget usage for a moment (a storage outage), requests are allowed rather than blocked.