Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
7749eb6
feat(proxy): add BudgetLimitEntry type and wire budget_limits into ke…
ishaan-jaff Mar 31, 2026
dedd91b
feat(schema): add budget_limits Json column to VerificationToken and …
ishaan-jaff Mar 31, 2026
37c8402
feat(migrations): add migration for budget_limits column on keys and …
ishaan-jaff Mar 31, 2026
cb9b1ee
feat(keys): initialize budget_limits windows with reset_at on key cre…
ishaan-jaff Mar 31, 2026
915924e
feat(teams): initialize budget_limits windows with reset_at on team c…
ishaan-jaff Mar 31, 2026
308d776
feat(auth): add _virtual_key_multi_budget_check and _team_multi_budge…
ishaan-jaff Mar 31, 2026
edce477
feat(auth): call multi-budget checks from common_checks for keys and …
ishaan-jaff Mar 31, 2026
7e7a609
feat(proxy): increment per-window Redis spend counters after each req…
ishaan-jaff Mar 31, 2026
497e7cc
feat(budget): reset individual budget windows on schedule via reset_b…
ishaan-jaff Mar 31, 2026
825681b
feat(ui): add hourly option to BudgetDurationDropdown
ishaan-jaff Mar 31, 2026
dbe0f8e
feat(ui): add budget_limits field to KeyResponse type
ishaan-jaff Mar 31, 2026
5c0a82f
feat(ui): add Budget Windows editor to key edit view
ishaan-jaff Mar 31, 2026
f4c1c87
feat(ui): add Budget Windows editor to create key form
ishaan-jaff Mar 31, 2026
0ebb954
fix(proxy): strip budget_limits=None before Prisma upsert to fix logi…
ishaan-jaff Apr 1, 2026
3c3179b
ui(key-edit): use antd InputNumber+Button for budget windows, add res…
ishaan-jaff Apr 1, 2026
ef68c93
ui(create-key): use antd InputNumber+Button for budget windows, add r…
ishaan-jaff Apr 1, 2026
cf16c19
docs(users): add multiple budget windows section with API + dashboard…
ishaan-jaff Apr 1, 2026
0890440
fix: BudgetExceededError returns HTTP 429 instead of 400
ishaan-jaff Apr 1, 2026
e33934a
fix: no-op else branch in multi-budget auth checks causes KeyError
ishaan-jaff Apr 1, 2026
7823b4e
fix: len() on JSON string returns char count not window count
ishaan-jaff Apr 1, 2026
7ec3775
fix: silent except:pass hides Redis reset failures in reset_budget_wi…
ishaan-jaff Apr 1, 2026
a6f92de
test: add unit tests for multi-budget window enforcement
ishaan-jaff Apr 1, 2026
b47f744
fix: key per-window counters stable across reorders (duration key, no…
ishaan-jaff Apr 1, 2026
99010c0
fix: team+key per-window spend increments use duration key, not index
ishaan-jaff Apr 1, 2026
b43d558
fix: budget window reset uses duration key; log failures instead of s…
ishaan-jaff Apr 1, 2026
5f4da7b
refactor: extract BudgetWindowsEditor to shared component
ishaan-jaff Apr 1, 2026
0e463ad
refactor: key_edit_view imports BudgetWindowsEditor from shared compo…
ishaan-jaff Apr 1, 2026
8911e5d
refactor: create_key_button imports BudgetWindowsEditor from shared c…
ishaan-jaff Apr 1, 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
61 changes: 61 additions & 0 deletions docs/my-website/docs/proxy/users.md
Original file line number Diff line number Diff line change
Expand Up @@ -333,6 +333,67 @@ curl 'http://0.0.0.0:4000/key/generate' \
}'
```

#### **Set multiple budget windows on a key**

Apply multiple concurrent budget limits at different time scales on the same key — for example, cap a key at **$10/day** AND **$100/month**.

**When is this useful?**

A single `budget_duration` window can't prevent a bad day from burning your entire month. Multiple budget windows let you:

- Block a runaway usage spike within the day while still allowing normal monthly spend.
- Give Claude Code rollouts a daily guardrail (`24h`) and a monthly ceiling (`30d`) so a single heavy session doesn't exhaust the whole month.
- Layer fine-grained hourly limits for bursty workloads on top of a weekly cap.

:::info

See [User Budget docs](https://docs.litellm.ai/docs/proxy/users) for more on how budgets work across keys, teams, and users.

:::

**Via API**

Pass `budget_limits` as a list of `{budget_duration, max_budget}` objects:

```bash
curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"budget_limits": [
{"budget_duration": "24h", "max_budget": 10},
{"budget_duration": "30d", "max_budget": 100}
]
}'
```

Each window is tracked independently and resets on its own schedule:

| `budget_duration` | Resets |
|---|---|
| `1h` | Every hour |
| `24h` | Daily at midnight UTC |
| `7d` | Every Sunday at midnight UTC |
| `30d` | 1st of every month at midnight UTC |

**Via Dashboard**

Open **Virtual Keys → Create Key → Optional Settings → Budget Windows**.

![Step 1 - open key settings](https://colony-recorder.s3.amazonaws.com/files/2026-04-01/18930ba5-67c0-4031-afc0-57f37b4e59e4/ascreenshot_ef79d8a000bb41cdacf1bd9827732ee8_text_export.jpeg)

Click **+ Add Budget Window** to add a row, choose the period from the dropdown, and enter the spend cap.

![Step 2 - add a window](https://colony-recorder.s3.amazonaws.com/files/2026-04-01/5ae8c0b3-2d03-41ad-a63c-47b20c350dfe/ascreenshot_1a7dc6c7d65544f38fd8a65604674f22_text_export.jpeg)

Add a second row for a different time period (e.g. monthly $100 on top of a daily $10).

![Step 3 - add second window](https://colony-recorder.s3.amazonaws.com/files/2026-04-01/cbded3a7-1086-4e20-8f0f-de154b76146c/ascreenshot_c51c18752c3b4f8b976d28799b2638b6_text_export.jpeg)

Each window shows the reset schedule below the input so it's always clear when spend resets.

![Step 4 - reset hints](https://colony-recorder.s3.amazonaws.com/files/2026-04-01/8754f121-1640-4892-9dd0-fd4a870418bf/ascreenshot_8079eb0df2194e8f99e5258ba4b3c082_text_export.jpeg)


### ✨ Virtual Key (Model Specific)

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
-- AlterTable: add budget_limits column to LiteLLM_VerificationToken
ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN IF NOT EXISTS "budget_limits" JSONB;

-- AlterTable: add budget_limits column to LiteLLM_TeamTable
ALTER TABLE "LiteLLM_TeamTable" ADD COLUMN IF NOT EXISTS "budget_limits" JSONB;
2 changes: 2 additions & 0 deletions litellm-proxy-extras/litellm_proxy_extras/schema.prisma
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
datasource client {
provider = "postgresql"
url = env("DATABASE_URL")
Expand Down Expand Up @@ -140,6 +140,7 @@
team_member_permissions String[] @default([])
access_group_ids String[] @default([])
policies String[] @default([])
budget_limits Json? // multiple concurrent budget windows [{budget_duration, max_budget, reset_at}]
model_id Int? @unique // id for LiteLLM_ModelTable -> stores team-level model aliases
allow_team_guardrail_config Boolean @default(false) // if true, team admin can configure guardrails for this team
litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id])
Expand Down Expand Up @@ -386,6 +387,7 @@
rotation_interval String? // How often to rotate (e.g., "30d", "90d")
last_rotation_at DateTime? // When this key was last rotated
key_rotation_at DateTime? // When this key should next be rotated
budget_limits Json? // multiple concurrent budget windows [{budget_duration, max_budget, reset_at}]
litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id])
litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id])
litellm_project_table LiteLLM_ProjectTable? @relation(fields: [project_id], references: [project_id])
Expand Down
3 changes: 2 additions & 1 deletion litellm/exceptions.py
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ def __repr__(self):
return _message


class PermissionDeniedError(openai.PermissionDeniedError): # type:ignore
class PermissionDeniedError(openai.PermissionDeniedError): # type: ignore
def __init__(
self,
message,
Expand Down Expand Up @@ -847,6 +847,7 @@ def __init__(
):
self.current_cost = current_cost
self.max_budget = max_budget
self.status_code = 429
message = (
message
or f"Budget has been exceeded! Current cost: {current_cost}, Max budget: {max_budget}"
Expand Down
116 changes: 68 additions & 48 deletions litellm/proxy/_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -862,6 +862,14 @@ class LiteLLM_ObjectPermissionBase(LiteLLMPydanticObjectBase):
models: Optional[List[str]] = None


class BudgetLimitEntry(LiteLLMPydanticObjectBase):
"""A single budget window with its own limit and independent reset schedule."""

budget_duration: str # e.g. "24h", "7d", "30d"
max_budget: float # max spend in USD for this window
reset_at: Optional[datetime] = None # populated at creation/reset time


class GenerateRequestBase(LiteLLMPydanticObjectBase):
"""
Overlapping schema between key and user generate/update requests
Expand All @@ -881,12 +889,15 @@ class GenerateRequestBase(LiteLLMPydanticObjectBase):
rpm_limit: Optional[int] = None

budget_duration: Optional[str] = None
budget_limits: Optional[List[BudgetLimitEntry]] = (
None # multiple concurrent budget windows
)
allowed_cache_controls: Optional[list] = []
config: Optional[dict] = {}
permissions: Optional[dict] = {}
model_max_budget: Optional[
dict
] = {} # {"gpt-4": 5.0, "gpt-3.5-turbo": 5.0}, defaults to {}
model_max_budget: Optional[dict] = (
{}
) # {"gpt-4": 5.0, "gpt-3.5-turbo": 5.0}, defaults to {}

model_config = ConfigDict(protected_namespaces=())
model_rpm_limit: Optional[dict] = None
Expand Down Expand Up @@ -985,6 +996,7 @@ def set_model_info(cls, values):
"permissions",
"model_max_budget",
"router_settings",
"budget_limits",
]
for field in dict_fields:
value = values.get(field)
Expand Down Expand Up @@ -1028,9 +1040,9 @@ class RegenerateKeyRequest(GenerateKeyRequest):
spend: Optional[float] = None
metadata: Optional[dict] = None
new_master_key: Optional[str] = None
grace_period: Optional[
str
] = None # Duration to keep old key valid (e.g. "24h", "2d"); None = immediate revoke
grace_period: Optional[str] = (
None # Duration to keep old key valid (e.g. "24h", "2d"); None = immediate revoke
)


class ResetSpendRequest(LiteLLMPydanticObjectBase):
Expand Down Expand Up @@ -1540,12 +1552,12 @@ class NewCustomerRequest(BudgetNewRequest):
blocked: bool = False # allow/disallow requests for this end-user
budget_id: Optional[str] = None # give either a budget_id or max_budget
spend: Optional[float] = None
allowed_model_region: Optional[
AllowedModelRegion
] = None # require all user requests to use models in this specific region
default_model: Optional[
str
] = None # if no equivalent model in allowed region - default all requests to this model
allowed_model_region: Optional[AllowedModelRegion] = (
None # require all user requests to use models in this specific region
)
default_model: Optional[str] = (
None # if no equivalent model in allowed region - default all requests to this model
)
object_permission: Optional[LiteLLM_ObjectPermissionBase] = None

@model_validator(mode="before")
Expand All @@ -1568,12 +1580,12 @@ class UpdateCustomerRequest(LiteLLMPydanticObjectBase):
blocked: bool = False # allow/disallow requests for this end-user
max_budget: Optional[float] = None
budget_id: Optional[str] = None # give either a budget_id or max_budget
allowed_model_region: Optional[
AllowedModelRegion
] = None # require all user requests to use models in this specific region
default_model: Optional[
str
] = None # if no equivalent model in allowed region - default all requests to this model
allowed_model_region: Optional[AllowedModelRegion] = (
None # require all user requests to use models in this specific region
)
default_model: Optional[str] = (
None # if no equivalent model in allowed region - default all requests to this model
)
object_permission: Optional[LiteLLM_ObjectPermissionBase] = None


Expand Down Expand Up @@ -1638,6 +1650,9 @@ class TeamBase(LiteLLMPydanticObjectBase):
max_budget: Optional[float] = None
soft_budget: Optional[float] = None
budget_duration: Optional[str] = None
budget_limits: Optional[List[BudgetLimitEntry]] = (
None # multiple concurrent budget windows
)

models: list = []
blocked: bool = False
Expand All @@ -1663,15 +1678,15 @@ class NewTeamRequest(TeamBase):
] = None # raise an error if 'guaranteed_throughput' is set and we're overallocating tpm

model_tpm_limit: Optional[Dict[str, int]] = None
team_member_budget: Optional[
float
] = None # allow user to set a budget for all team members
team_member_rpm_limit: Optional[
int
] = None # allow user to set RPM limit for all team members
team_member_tpm_limit: Optional[
int
] = None # allow user to set TPM limit for all team members
team_member_budget: Optional[float] = (
None # allow user to set a budget for all team members
)
team_member_rpm_limit: Optional[int] = (
None # allow user to set RPM limit for all team members
)
team_member_tpm_limit: Optional[int] = (
None # allow user to set TPM limit for all team members
)
team_member_key_duration: Optional[str] = None # e.g. "1d", "1w", "1m"
team_member_budget_duration: Optional[str] = None # e.g. "30d", "1mo"
allowed_vector_store_indexes: Optional[List[AllowedVectorStoreIndexItem]] = None
Expand Down Expand Up @@ -1736,6 +1751,9 @@ class UpdateTeamRequest(LiteLLMPydanticObjectBase):
enforced_file_expires_after: Optional[dict] = None
router_settings: Optional[dict] = None
access_group_ids: Optional[List[str]] = None
budget_limits: Optional[List[BudgetLimitEntry]] = (
None # multiple concurrent budget windows
)


class ResetTeamBudgetRequest(LiteLLMPydanticObjectBase):
Expand Down Expand Up @@ -1768,9 +1786,9 @@ class BlockKeyRequest(LiteLLMPydanticObjectBase):

class AddTeamCallback(LiteLLMPydanticObjectBase):
callback_name: str
callback_type: Optional[
Literal["success", "failure", "success_and_failure"]
] = "success_and_failure"
callback_type: Optional[Literal["success", "failure", "success_and_failure"]] = (
"success_and_failure"
)
callback_vars: Dict[str, str]

@model_validator(mode="before")
Expand Down Expand Up @@ -1879,6 +1897,7 @@ def set_model_info(cls, values):
"model_max_budget",
"model_aliases",
"router_settings",
"budget_limits",
]

if isinstance(values, BaseModel):
Expand Down Expand Up @@ -2110,9 +2129,9 @@ class ConfigList(LiteLLMPydanticObjectBase):
stored_in_db: Optional[bool]
field_default_value: Any
premium_field: bool = False
nested_fields: Optional[
List[FieldDetail]
] = None # For nested dictionary or Pydantic fields
nested_fields: Optional[List[FieldDetail]] = (
None # For nested dictionary or Pydantic fields
)


class UserHeaderMapping(LiteLLMPydanticObjectBase):
Expand Down Expand Up @@ -2361,6 +2380,7 @@ class LiteLLM_VerificationToken(LiteLLMPydanticObjectBase):
last_rotation_at: Optional[datetime] = None # When this key was last rotated
key_rotation_at: Optional[datetime] = None # When this key should next be rotated
router_settings: Optional[dict] = None
budget_limits: Optional[List[dict]] = None # multiple concurrent budget windows
model_config = ConfigDict(protected_namespaces=())


Expand Down Expand Up @@ -2470,9 +2490,9 @@ class UserAPIKeyAuth(
user_max_budget: Optional[float] = None
request_route: Optional[str] = None
user: Optional[Any] = None # Expanded user object when expand=user is used
created_by_user: Optional[
Any
] = None # Expanded created_by user when expand=user is used
created_by_user: Optional[Any] = (
None # Expanded created_by user when expand=user is used
)
end_user_object_permission: Optional[LiteLLM_ObjectPermissionTable] = None
# Decoded upstream IdP claims (groups, roles, etc.) propagated by JWT auth machinery
# and forwarded into outbound tokens by guardrails such as MCPJWTSigner.
Expand Down Expand Up @@ -2611,9 +2631,9 @@ class LiteLLM_OrganizationMembershipTable(LiteLLMPydanticObjectBase):
budget_id: Optional[str] = None
created_at: datetime
updated_at: datetime
user: Optional[
Any
] = None # You might want to replace 'Any' with a more specific type if available
user: Optional[Any] = (
None # You might want to replace 'Any' with a more specific type if available
)
litellm_budget_table: Optional[LiteLLM_BudgetTable] = None
user_email: Optional[str] = None

Expand Down Expand Up @@ -3764,9 +3784,9 @@ class TeamModelDeleteRequest(BaseModel):
# Organization Member Requests
class OrganizationMemberAddRequest(OrgMemberAddRequest):
organization_id: str
max_budget_in_organization: Optional[
float
] = None # Users max budget within the organization
max_budget_in_organization: Optional[float] = (
None # Users max budget within the organization
)


class OrganizationMemberDeleteRequest(MemberDeleteRequest):
Expand Down Expand Up @@ -4017,9 +4037,9 @@ class ProviderBudgetResponse(LiteLLMPydanticObjectBase):
Maps provider names to their budget configs.
"""

providers: Dict[
str, ProviderBudgetResponseObject
] = {} # Dictionary mapping provider names to their budget configurations
providers: Dict[str, ProviderBudgetResponseObject] = (
{}
) # Dictionary mapping provider names to their budget configurations


class ProxyStateVariables(TypedDict):
Expand Down Expand Up @@ -4163,9 +4183,9 @@ class LiteLLM_JWTAuth(LiteLLMPydanticObjectBase):
enforce_rbac: bool = False
roles_jwt_field: Optional[str] = None # v2 on role mappings
role_mappings: Optional[List[RoleMapping]] = None
object_id_jwt_field: Optional[
str
] = None # can be either user / team, inferred from the role mapping
object_id_jwt_field: Optional[str] = (
None # can be either user / team, inferred from the role mapping
)
scope_mappings: Optional[List[ScopeMapping]] = None
enforce_scope_based_access: bool = False
enforce_team_based_model_access: bool = False
Expand Down
Loading
Loading