A budget in AI Cost Management tracks AI spend against a limit and sends alerts as spend approaches it. If a team’s AI usage can run past what your organization planned to spend, budgets give you an early signal while there’s still time to react.
Budgets only observe spend and send alerts, so requests continue after spend reaches the limit.
You can send budget alerts to notification channels.
Common use cases for budgets:
|
Use case |
Description |
|---|---|
| Cap total AI spend | Set one limit on all AI usage in your organization with an organization-wide budget, so you know when overall spend nears a planned amount. |
| Share one allowance across groups | Give several groups a combined limit with a pooled budget, so their spend counts against the same allowance. |
| Give every group or user the same cap | Split the limit by a field, so every group, user, provider, or model gets its own limit from a single budget. |
| Watch one provider or model | Scope a budget to a provider or model with a filter, so you see when spend on a costly model grows. |
| Get an early warning | Add notification thresholds below the limit, like 50 and 80 percent, to alert people while there’s time to react. A threshold above 100 percent alerts on spend beyond the limit. |
To create a provider budget that sends early warnings to a channel, follow one of these guides:
A budget goes through the following steps from request to alert:
sequenceDiagram
autonumber
participant GW as AI Gateway
participant ACM as AI Cost Management
participant CH as Notification channels
GW->>ACM: Report cost of each AI request as usage
ACM->>ACM: Match usage against the scope of each budget
ACM->>ACM: Add the cost to the spend in the current budget window
alt If spend reaches a threshold <br>in the notification rule
ACM->>CH: Send an alert
ACM->>ACM: Record a notification event
endFigure 1: Diagram showing how a budget tracks spend and sends alerts.
A request can match several budgets. The request counts toward every budget it matches, and AI Cost Management evaluates each budget on its own.
For example, you have two budgets:
An OpenAI request counts toward both budgets, and the OpenAI budget sends alerts at its own thresholds, based on OpenAI spend alone.
The scope of a budget selects which AI requests count toward its spend limit.
A scope has filters, and it can split the budget into one limit per value of a field. Filters narrow a budget to the usage you want it to cover. Each filter compares a usage field (for example, a provider, model, or tag) with a value. Usage counts toward the budget only when it matches all of the filters.
A budget with no filters counts all usage in your organization.
A filter uses an operator like eq, neq, in, contains, or exists to compare a field with a value.
The subject and group fields don’t accept contains or ocontains.
A filter group combines several filters with and or or, and a group can contain further groups.
A scope allows at most 15 conditions in total, nested at most 4 groups deep.
Budgets can apply their spend limits in one of the following ways:
|
Limit type |
Description |
When to use |
|---|---|---|
| Pooled limit |
In a pooled limit, one limit applies to all the usage in scope.
A budget pools its usage by default.
A pooled limit can cover the usage that matches a set of filters, or all usage in your organization. |
Choose a pooled limit when the usage in scope shares one allowance, like a team with a single monthly allowance. |
| Individual limit | With an individual limit, you choose a field to split the budget by, and every value of that field gets its own limit. Each value gets a derived budget with the same limit. Usage with no value for that field doesn’t count toward any derived budget. One budget covers all of its values, so you don’t create a budget for each one. | Choose an individual limit when every value needs the same cap, like every user or every model. |
Either limit works with any scope, including a scope with no filters, which covers all usage in your organization. For example, a pooled limit on an empty scope is one limit for your whole organization, and an individual limit on an empty scope gives every user, provider, or model the same cap.
The limit sets the spend a budget allows in one budget window.
Set the limit as an amount in US dollars, for example 500 or 0.2.
USDis the only supported currency.
The size of a budget window is fixed. Consecutive windows have the same length and align to an anchor.
Windows start a whole number of intervals before or after the anchor, in the local time of the anchor’s time zone. Calendar units like months therefore stay aligned to the calendar. A window that would start on a day its month doesn’t have, like the 31st, starts on the last day of that month.
The balance of a limit budget shows spend, the amount remaining, and projected spend for one budget window.
By default, the balance covers the current budget window. It can also cover an earlier budget window, chosen by a time within the window. The balance counts the usage stored when you request it, so a request that finished moments ago can take a short time to appear.
Each amount in a balance is a value and a currency, for example { "value": "499.9998412", "currency": "USD" }.
A balance has the following fields:
|
Field |
Description |
|---|---|
consumed
|
The spend of all usage in the budget’s scope during the budget window. |
remaining
|
The limit minus consumed. The value is negative once spend exceeds the limit.
|
projected
|
The spend expected by the end of the budget window at the current pace, rounded to the cent. The pace extrapolates consumed over the whole window from the share that has elapsed.
The calculation uses a minimum share of one twentieth of the window.
|
latest_record_at
|
When the newest usage counted in the balance reached the service. The value is null when no usage matches.
|
derived
|
For a budget with each, the balances of the derived budgets with the highest spend, highest first. The size query parameter sets how many, up to 100.
|
A notification rule alerts channels as a budget’s spend reaches thresholds. Each limit budget can have one rule. A rule has thresholds, channels, and an optional custom message. The rule sends alerts to notification channels, which you create once and list in the rules of any budget. A rule can list up to 10 channels.
A threshold is a share of the limit, set as a whole percent from 1 to 1000. Spend reaches a threshold when it equals or exceeds that share of the limit. A threshold above 100 alerts on spend beyond the limit. A threshold never blocks a request.
A rule holds up to 10 thresholds, and each threshold uses a different percent. Each threshold triggers an alert at most once per budget window, derived budget, and limit. When one evaluation finds several thresholds reached, only the highest sends an alert. The lower thresholds still appear as notification events, with no deliveries. When you change the limit, the thresholds can trigger alerts again.
When you create or replace a rule, AI Cost Management evaluates it right away. A threshold that spend has already reached in the current budget window sends an alert, unless a higher threshold has already sent one.
By default, alerts use a standard template, which includes:
To change the wording of an alert on every channel, you can set up a custom message with a subject and a body. The subject is a single line of 1 to 200 characters. The body is plain text of 1 to 2000 characters, and a blank line starts a new paragraph.
Both fields can contain placeholders in double curly braces, for example {{budget.name}}.
AI Cost Management replaces each placeholder with the value for that alert.
Monetary amounts appear in US dollars, for example $4,125.50.
The custom message accepts any of the following placeholders:
|
Placeholder |
Value |
|---|---|
budget.name
|
The budget’s name. |
budget.url
|
A link to the budget in Konnect. |
threshold
|
The threshold that spend reached, like 80%.
|
limit
|
The limit that spend is measured against. With each, the limit of one derived budget.
|
spend
|
The spend so far in the budget window. |
percent
|
The spend as a share of the limit, like 82.51%.
|
remaining
|
What is left of the limit, never below $0.00.
|
projected
|
The spend expected by the end of the budget window at the current pace, as an amount and a share of the limit. |
period
|
The budget window, in the time zone of its anchor. |
period.start
|
When the budget window started. |
period.end
|
When the budget window ends and the budget resets. |
period.remaining
|
How long is left in the budget window, like 8 days or 3 hours.
|
entity.field
|
The each field as a noun: group, user for subject, or env tag for tags.env.
|
entity.value
|
The value whose derived budget reached the threshold. |
Note: The
entity.fieldandentity.valueplaceholders work only on a budget witheach. An unknown placeholder, or anentityplaceholder on a budget withouteach, is rejected with an error.
The following custom message template uses placeholders for a budget that splits its limit by group:
Subject: [Kong Konnect] Budget "{{budget.name}}" reached {{threshold}} of its limit
Body: The {{entity.field}} {{entity.value}} used {{spend}} of its {{limit}} limit ({{percent}}), with {{period.remaining}} left in the period.For example, if you have a budget named Model spend with an 80% threshold, the template produces this alert:
[Kong Konnect] Budget "Model spend" reached 80% of its limit
The group group/example used $4,125.50 of its $5,000.00 limit (82.51%), with 5 days left in the period.A notification event records each time spend reaches a threshold for a budget.
To list events or get one by ID, use the /v1/ai-cost-management/notification-events endpoints.
AI Cost Management records an event only after it has stored and evaluated the usage that reached the threshold, so an event can show up some time after the request that caused it.
The following sample event shows an 80% threshold reached by a pooled budget, with one delivery to an email channel:
{
"id": "0198c5b6-d000-7000-8000-000000000101",
"kind": "threshold",
"budget": {
"id": "0198c5b6-d000-7000-8000-000000000001",
"name": "Model spend",
"effect": "limit",
"labels": {},
"scope": {
"filters": [
{
"field": "provider",
"op": "eq",
"value": "openai"
}
],
"each": null
},
"priority": 100,
"limit": {
"currency": "USD",
"value": "5000"
},
"window": {
"type": "fixed",
"interval": "P1M",
"anchor": "2026-01-01T00:00:00+00:00[UTC]"
},
"created_at": "2026-06-01T09:00:00Z",
"updated_at": "2026-06-01T09:00:00Z"
},
"threshold": {
"percent": 80
},
"value": null,
"window": {
"start": "2026-07-01T00:00:00Z",
"end": "2026-08-01T00:00:00Z"
},
"limit": {
"currency": "USD",
"value": "5000"
},
"consumed": {
"currency": "USD",
"value": "4031.4"
},
"fired_at": "2026-07-27T14:05:00Z",
"deliveries": [
{
"channel": {
"id": "0198c5b6-d000-7000-8000-000000000201",
"name": "budget-alerts-email",
"type": "email"
},
"status": "delivered",
"error": null,
"updated_at": "2026-07-27T14:05:02Z"
}
]
}The value field is null because the budget is pooled.
For a budget with each, value holds the value whose derived budget reached the threshold.
A lower threshold that didn’t send an alert has the same shape, with an empty deliveries array.