# Budgets

> Set daily, weekly or monthly spending limits for the organization, a team or a person, with warnings in responses before anything is blocked.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/govern/budgets. Last updated: 2026-10-16.

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](https://tessarac.com/docs/acog/optimize/savings-measurement.md)), 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:

```bash
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:

```json
{
  "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](https://tessarac.com/docs/acog/administer/webhooks.md) 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.