Skip to content

docs(ai-coder/ai-gateway): use approximate spend and add Everyone group tip #28012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ssncferreira wants to merge 3 commits into
base: main
Choose a base branch
from
+383 −242
Draft

docs(ai-coder/ai-gateway): use approximate spend and add Everyone group tip #28012

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89740ab
test(enterprise/cli): add standalone AI Gateway connection tests
pawbana Aug 6, 2026
9bcc0a2
docs(ai-coder/ai-gateway): use approximate spend and add Everyone gro…
ssncferreira Aug 11, 2026
58ccbef
docs(ai-coder/ai-gateway): rename spend section to How spend is calcu…
ssncferreira Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 20 additions & 18 deletions docs/ai-coder/ai-gateway/cost-controls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,20 @@ AI Governance Cost Control requires:
- AI Gateway [enabled and configured](./setup.md) with at least one provider.

> [!NOTE]
> AI Governance Cost Control reports estimated spend rather than billed cost.
> Estimates will not match your provider invoices exactly. For details, see
> [How spend is estimated](#how-spend-is-estimated).
> AI Governance Cost Control reports approximate spend rather than billed cost.
> These figures will not match your provider invoices exactly. For details, see
> [How spend is calculated](#how-spend-is-calculated).

These terms appear throughout this page and in the Coder dashboard:

| Term | What it means | Where it is set |
|---------------------|---------------------------------------------------------------------------------------|----------------------------------------|
| **Budget period** | The window spend accumulates in before it resets. Defaults to the UTC calendar month. | Deployment settings |
| **Budget policy** | The rule that selects a user's effective group. Defaults to the highest budget. | Deployment settings |
| **Group budget** | A spend limit granted to each member of a group. | **Groups** > {group} > **Settings** |
| **User override** | A spend limit for one user that supersedes their group budget. | **Groups** > {group} > **Members** tab |
| **Effective group** | The group that supplies a user's budget and has their spend associated with it. | Resolved automatically |
| **Estimated spend** | A user's approximate spend in the current budget period. | Estimated from usage |
| Term | What it means | Where it is set |
|-----------------------|---------------------------------------------------------------------------------------|----------------------------------------|
| **Budget period** | The window spend accumulates in before it resets. Defaults to the UTC calendar month. | Deployment settings |
| **Budget policy** | The rule that selects a user's effective group. Defaults to the highest budget. | Deployment settings |
| **Group budget** | A spend limit granted to each member of a group. | **Groups** > {group} > **Settings** |
| **User override** | A spend limit for one user that supersedes their group budget. | **Groups** > {group} > **Members** tab |
| **Effective group** | The group that supplies a user's budget and has their spend associated with it. | Resolved automatically |
| **Approximate spend** | A user's approximate spend in the current budget period. | Calculated from usage |

## Deployment settings

Expand Down Expand Up @@ -181,7 +181,7 @@ affected user:
For delivery methods, see
[Notifications](../../admin/monitoring/notifications/index.md).

## How spend is estimated
## How spend is calculated

Coder multiplies the token usage of each request by the published price of the
model that served it. Prices come from a curated [models.dev](https://models.dev)
Expand All @@ -200,10 +200,10 @@ https://github.com/coder/coder/blob/release/<VERSION>/coderd/aibridge/prices/dat
Replace `<VERSION>` with your Coder minor version, for example `2.36`.

> [!IMPORTANT]
> Estimated spend can differ from provider-reported amounts, and some usage might
> not count toward spend:
> Approximate spend can differ from provider-reported amounts, and some usage
> might not count toward spend:
>
> - Estimates exclude negotiated discounts, committed-use pricing, and
> - Approximate spend excludes negotiated discounts, committed-use pricing, and
> provider-specific billing rules.
> - Requests to models that are missing from the price table record token usage
> but add nothing to a user's spend. A user who only calls unpriced models is
Expand Down Expand Up @@ -236,7 +236,9 @@ Visibility follows the viewer's role:
group budget. If the effective group is another group in the same organization,
the row shows `Budget managed by another group`. If the effective group is in a
different organization, the row shows a dash and explains that the group is not
visible there.
visible there. Because the organization's `Everyone` group includes every
member, its **Members** tab is a quick way to look up any user's effective
group.
- The avatar menu reports the signed-in user's own spend for the budget period
as `$<spend> / $<budget> USD`, or `$<spend> / Unlimited USD` when no budget
applies.
Expand All @@ -247,7 +249,7 @@ endpoint to see a user's current effective group.

### CSV Export

Users who can read group-member data for the organization can export estimated
Users who can read group-member data for the organization can export approximate
spend for reporting and internal cost allocation. The export is available through
the API only.

Expand Down Expand Up @@ -294,7 +296,7 @@ Expect the following differences:
Control applied the lowest.
- Budgets cover priced AI Gateway traffic. Chat, IDE extensions, and CLI agents
draw on the same budget when their provider and model are priced. See
[How spend is estimated](#how-spend-is-estimated).
[How spend is calculated](#how-spend-is-calculated).
- Recorded spend does not carry over. Every user starts the first period at
$0 USD.
- Coder Agents users who exceed their budget see a usage limit error in chat.
Expand Down
Loading
Loading