Enforcement

Per-user budgets

Per-user budgets let you set a spend limit for a specific user ID. They work the same way as tier templates but target one user rather than an entire tier. A per-user budget always takes precedence over any matching tier template.

When to use per-user budgets

  • A specific user needs a higher limit than their tier — a power user on a free plan you want to accommodate
  • A specific user needs a lower limit — a user showing unusual usage patterns you want to cap
  • You don't use tiers at all and want to manage limits user by user

For most teams, tier templates are the better starting point. Per-user budgets are an override mechanism, not the primary way to configure enforcement.

Step 1 — Create a budget in the dashboard

Go to Enforcement and click + New override. Configure:

User IDMust match exactly the userId value you pass in your SDK calls. Case-sensitive.
Spend limitMaximum USD spend per window for this user.
WindowThe rolling period — day, week, or month.
ActionWhat happens when the limit is reached. warn is the default — calls proceed and onBudgetWarning fires. block throws LLMBudgetExceededError.
Alert thresholdFire onBudgetWarning at this percentage of the limit. Default 80%.

Step 2 — No call-site changes needed

If you're already passing userId on your calls, per-user budgets work automatically. The SDK looks up the budget by user ID on every call — nothing changes at the call site.

import { trackedCall } from '@llmcosttracker/sdk'// No changes needed — userId is already thereawait trackedCall({client, params, apiKey: 'lct_live_your_key_here', group: 'search', userId: session.userId,})

Precedence over tier templates

When the SDK looks up a budget for a call it checks in this order:

  1. Per-user budget matching this userId — if found, use it
  2. Tier template matching the tier tag — if found, use it
  3. No enforcement — call proceeds normally

A per-user budget completely replaces the tier template for that user. If a free-tier user has a per-user budget of $20, the free tier template limit is ignored for them entirely.

Disabling vs deleting

You can disable a per-user budget without deleting it — the toggle in the dashboard pauses enforcement while preserving the configuration. The spend counter is preserved so history is not lost. Re-enabling picks up where it left off within the current window.

Spend counter reset

Counters reset automatically at the start of each window period in UTC. A monthly budget resets on the 1st of each month at 00:00 UTC regardless of when it was created.

Next: Handling blocks →