Skip to main content

Budgets and pricing

A budget caps model spend in USD for a directory user or group. The AI Gateway checks available budget before sending a request and charges provider-reported usage after the response.

Use Budgets in the console for routine administration. Use the REST API for automation, bulk import, and pricing.

Cover every caller before you turn enforcement on

Budget enforcement denies callers without an applicable budget. Cover every caller before enabling enforcement.

Prerequisites​

Budget enforcement runs through gateway-level webhooks.

Confirm that both budget entries report probeSucceeded: true:

kubectl get aigw <NAME> -n <NAMESPACE> \
  -o jsonpath='{.status.webhooks}' | jq .

A false value usually indicates mismatched audiences on the gateway and budget service.

Cover every caller first​

Before enabling budget enforcement for an environment with traffic, choose one of these approaches:

Set an organization default. This covers directory users without an explicit budget. Set it on the Defaults tab or through the API.

Create budgets individually. Use the bulk import for an existing user and group inventory.

The organization default applies only to resolved directory users, not to service accounts.

Create budgets​

Each budget has a USD limit and a daily, monthly, or yearly calendar period. The budgets endpoints are part of the Enterprise Manager API.

The API identifies a budget by scope and subject. scope is user, group, or service_account. subject_id is the user's directory UUID, the directory group's UUID, or the directory service account's UUID. Find a user's UUID in the id field that GET /v1/users returns. That endpoint accepts an email filter. limit_usd is a decimal string and period is day, month, or year.

Set an organization default​

Set the organization default on the Defaults tab or through the API:

curl -X PUT https://<ENTERPRISE_MANAGER_URL>/v1/budgets/default \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": "350.000000000", "period": "day"}'

Setting the default replaces its previous value. Deleting it leaves users without explicit budgets uncovered. Moving a user between the default and an explicit budget preserves their current-period usage.

Update one budget​

Use the user or group endpoint to create or update one budget:

curl -X PUT https://<ENTERPRISE_MANAGER_URL>/v1/budgets/users/<USER_UUID> \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": "5.000000000", "period": "day"}'

curl -X PUT https://<ENTERPRISE_MANAGER_URL>/v1/budgets/groups/<GROUP_UUID> \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": "500.000000000", "period": "month", "precedence": 1}'

Group budgets use 1-based precedence. The gateway charges an explicit user budget first.

Workloads that call the gateway with a Kubernetes service account token are charged to a service account budget, set with PUT /v1/budgets/service-accounts/<SERVICE_ACCOUNT_UUID>. The organization default never covers a service account, so give each calling workload its own budget or a group budget.

Import in bulk​

PUT /v1/budgets replaces the entire collection: budgets in the request are created or updated, and budgets absent from the request are deleted. Use it only for complete imports.

curl -X PUT https://<ENTERPRISE_MANAGER_URL>/v1/budgets \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "budgets": [
      {"scope": "user",  "subject_id": "<USER_UUID>", "limit_usd": "5.000000000",   "period": "day"},
      {"scope": "group", "subject_id": "<GROUP_UUID>", "limit_usd": "500.000000000", "period": "month"}
    ]
  }'

Bulk replacement preserves spend counters. A bulk import takes no precedence field. Group budgets are charged in the order their entries appear in the request, and the import renumbers every group, replacing any precedence you set through the per-group endpoint.

GET /v1/budgets returns the collection with an ETag. Send it back as If-Match on your next write to detect a concurrent change; a 412 response means re-read and retry.

Which budget gets charged​

The gateway charges budgets in this order:

  1. The user's explicit budget, or the organization default.
  2. The first group budget with remaining capacity, ordered by ascending precedence.

The gateway denies the request when no applicable budget has capacity.

Update the pricing catalog​

Enterprise Manager ships a baseline catalog generated weekly from public model pricing, and each upgrade refreshes every rate you haven't changed. To override a price, update one model's entry at a time through the API. Changes take effect without a restart.

GET /v1/budgets/pricing returns the active catalog with an ETag header. Send that value as If-Match with a PUT to the entry's address, /v1/budgets/pricing/entries/<PROVIDER>/<MODEL>. Use the provider and model exactly as they appear in the catalog. A model name can contain /. The body carries exactly one rate block: anthropic, openai, or google.

curl -i https://<ENTERPRISE_MANAGER_URL>/v1/budgets/pricing \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

curl -X PUT https://<ENTERPRISE_MANAGER_URL>/v1/budgets/pricing/entries/anthropic/claude-sonnet-4-6 \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H 'If-Match: <ETAG>' \
  -H "Content-Type: application/json" \
  -d '{"anthropic": {"inputUsdPerMillion": "3", "outputUsdPerMillion": "15"}}'

The ETag identifies the whole catalog version, so a write to any entry changes it. A request without If-Match returns 428, and a stale value returns 412. Read the catalog again and retry.

Each write publishes a new complete catalog version, effective immediately. The entry you write stops tracking the baseline, so later upgrades leave its rate alone. Every other entry keeps tracking the baseline.

To withdraw or restore a rate, use these requests, which also require If-Match:

  • DELETE on the entry removes its rate. The gateway denies requests for that model until you price it again, and upgrades don't restore it.
  • POST to /v1/budgets/pricing/entries/<PROVIDER>/<MODEL>/revert returns the entry to the baseline's current rate. It returns 409 when the baseline doesn't price that model.

GET /v1/budgets/pricing/versions lists published catalog versions, and GET /v1/budgets/pricing/versions/<EFFECTIVE_FROM> returns one of them. To restore an earlier rate, read it from that version and PUT it on the entry.

Rate fields by provider​

Set provider-specific rates for cache creation, reasoning, audio, prompt-size tiers, and server-side tools when the model reports those usage categories. The examples below show entries as the catalog stores them. In a PUT body, send only the provider block. The provider and model come from the URL.

Anthropic reports cache-creation tokens split by time to live, so declare each rate separately:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "anthropic": {
    "inputUsdPerMillion": "3",
    "cacheCreation5mInputUsdPerMillion": "3.75",
    "cacheCreation1hInputUsdPerMillion": "6",
    "cachedInputUsdPerMillion": "0.3",
    "outputUsdPerMillion": "15"
  }
}

OpenAI reasoning models report reasoning tokens, and the audio families report audio input and output separately:

{
  "provider": "openai",
  "model": "gpt-4o-audio-preview",
  "openai": {
    "inputUsdPerMillion": "2.5",
    "cachedInputUsdPerMillion": "1.25",
    "outputUsdPerMillion": "10",
    "audioInputUsdPerMillion": "40",
    "audioOutputUsdPerMillion": "80"
  }
}

Some models charge a higher rate above a prompt-size threshold. Encode that with promptSizeTiers:

{
  "provider": "google",
  "model": "gemini-2.5-pro",
  "google": {
    "inputUsdPerMillion": "1.25",
    "cachedInputUsdPerMillion": "0.125",
    "outputUsdPerMillion": "10",
    "thoughtsOutputUsdPerMillion": "10",
    "promptSizeTiers": [
      {
        "aboveTokens": 200000,
        "inputUsdPerMillion": "2.5",
        "cachedInputUsdPerMillion": "0.25",
        "outputUsdPerMillion": "15"
      }
    ]
  }
}

Server-side tools that bill per thousand calls appear in the catalog's tools block, per provider rather than per model. These fees come from the baseline catalog, and the API can't change them:

{
  "entries": ["...per-model entries..."],
  "tools": {
    "anthropic": { "webSearchUsdPerThousand": "10" },
    "openai": {
      "webSearchUsdPerThousand": "10",
      "fileSearchUsdPerThousand": "2.5"
    },
    "google": { "groundingSearchUsdPerThousand": "35" }
  }
}

Monitor spend​

Use Budgets to compare usage with each limit.

Use the API for finance reports and external dashboards:

EndpointReturns
GET /v1/budgets/summaryUsed, limit, and remaining per principal for the period
GET /v1/budgets/spendA spend time series, for charting
GET /v1/budgets/breakdownCurrent-period spend for one budget, by user, model, or provider
GET /v1/budgets/chargesRecorded charges, newest first, with the exact amount charged
GET /v1/budgets/eventsRaw usage events, including those that resolved to no charge

GET /v1/budgets/groups/<ID> and GET /v1/budgets/users/<ID> return the same breakdown addressed per budget, with a dimension query parameter.

Any authenticated caller can read their own events, charges, summary, and spend series at /v1/me/budgets/events, /charges, /summary, and /spend without an admin grant. The admin routes above require the platform admin grant, the same one directory administration requires; there is no separate budgets role.

When a budget runs out​

An exhausted budget returns a policy denial. Check the caller in the console to distinguish an exhausted budget from missing coverage.

Access resumes when the calendar period resets. To restore access immediately, raise the limit. The change applies on the next request and preserves the usage counter.

Next steps​