Budgets

Set spend limits per user path and enforce them through workflow budget controls.

Overview

Budgets let you set spend limits for a user_path subtree. GoModel evaluates them from tracked usage cost records and blocks matching requests when a limit has already been spent.

Use budgets when you want limits such as:

• /team/alpha can spend $10 per day
• /team/alpha can spend $50 per week
• / has a global monthly limit

Budget enforcement runs only when budgets are globally enabled and the active workflow has Budget enabled. The Budget workflow control is enabled by default when the global budget feature is on.

Enable budgets

Budgets are enabled by default:

BUDGETS_ENABLED=true

Budgets depend on usage tracking because spend is calculated from usage cost records:

USAGE_ENABLED=true

If usage tracking is disabled, GoModel starts with budget management disabled and logs a warning.

Create budgets

You can create budgets in the dashboard:

Budgets -> Create Budget

Dashboard-created budgets are marked as manual. Budgets loaded from YAML or environment variables are marked as config.

You can also seed budgets from YAML:

budgets:
  enabled: true
  user_paths:
    - path: "/team/alpha"
      limits:
        - period: "daily"
          amount: 10.00
        - period: "weekly"
          amount: 50.00
    - path: "/"
      limits:
        - period: "monthly"
          amount: 500.00

Or use environment variables:

SET_BUDGET_TEAM__ALPHA="daily=10,weekly=50"
SET_BUDGET_="monthly=500"

The suffix after SET_BUDGET_ becomes a user path. Use double underscores (__) between path segments; single underscores remain part of a segment:

• SET_BUDGET_TEAM__ALPHA -> /team/alpha
• SET_BUDGET_USER_123 -> /user_123
• SET_BUDGET_ -> /

There is no escape for a literal double underscore inside a path segment. Use YAML or the dashboard for paths that need a __ segment value.

Supported standard periods are:

Period	Seconds
hourly	3600
daily	86400
weekly	604800
monthly	2592000

The Seconds column is the internal period identifier. Standard periods use the configured reset-anchor logic; for example, monthly is stored as 2592000 but resets on calendar month anchors and clamps the reset day to shorter months. Only custom period_seconds values behave as fixed-second windows.

For custom windows, set period_seconds in YAML:

budgets:
  user_paths:
    - path: "/team/alpha"
      limits:
        - period_seconds: 7200
          amount: 5.00

How matching works

Budget paths apply to the configured path and its descendants:

• budget path /team
• request path /team/app
• result: budget applies

Sibling paths do not match:

• budget path /team
• request path /team-alpha
• result: budget does not apply

If multiple budgets match a request, GoModel checks all matching limits. The request is rejected if any matching limit is exhausted.

Workflow enforcement

The active workflow controls whether budget checks run for a request.

In a workflow payload:

{
  "schema_version": 1,
  "features": {
    "budget": true,
    "cache": true,
    "audit": true,
    "usage": true,
    "guardrails": true,
    "fallback": true
  }
}

Use scoped workflows to turn budget enforcement on or off for a provider, model, or user_path subtree. See Workflows for matching precedence.

Response cache hits can return before budget enforcement. If a cached response exists, GoModel can serve it without spending additional provider cost.

Reset windows

Budget reset anchors are configured in the dashboard under:

Settings -> Budget Resets

The reset settings are evaluated in UTC.

For monthly budgets, if the configured day does not exist in a month, the reset runs on the last day of that month. For example, a monthly reset day of 31 runs on April 30 and on February 28 or 29.

Editing a budget changes the limit but does not reset the current period. Use the row-level Reset action to start a new period for one budget, or Settings -> Reset All Budgets to reset all budgets.

Admin API

Budget management is also available through the admin API:

curl -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  http://localhost:8080/admin/budgets

Create or update a budget:

curl -X PUT http://localhost:8080/admin/budgets/%2Fteam%2Falpha/daily \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00
  }'

Delete a budget:

curl -X DELETE http://localhost:8080/admin/budgets/%2Fteam%2Falpha/daily \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"

See Admin Endpoints for the endpoint list.