thelastapi
Get started free

Per-user AI budgets: stop one user from burning your AI bill

Set per-user daily AI budgets with thelastapi by tagging requests with your user ID and configuring end_user_daily_budget_usd on your project.

On this page 8 sections

You can limit AI API spend per user by tagging every AI request with a user identifier and setting an end-user daily budget on your project. When you send a user identifier via the user field, the X-Vibiz-User header, or @vibiz/app, the gateway meters spend per person and cuts off any user who exceeds end_user_daily_budget_usd with an OpenAI-compatible 429 rate_limited error. This prevents a single user, script, or runaway client session from exhausting your account balance or project budget.

Without per-user controls, protecting your spend requires blunt account-level or project-level ceilings. Here is how to configure per-user budgets, tag calls correctly, and handle refusals cleanly.

Why runaway user spend happens

When an application exposes AI chat, image generation, or document processing to end users, costs can spiral quickly:

  • Looping client requests: A buggy UI retry loop or aggressive client polling can fire hundreds of completions in minutes.
  • Power users and automation: A customer who pastes massive documents or scripts automated workflows into your interface consumes disproportionate compute compared to typical users.
  • Shared project budgets: If your project has a $10 daily budget, one aggressive user can consume the entire pool by 9:00 AM UTC, locking out every other user of your application.

Setting an account-level daily safety cap or a project AI budget protects your bank balance, but it does not protect your users from each other. If you want to know how to track AI spend per client and enforce boundaries before one customer starves the rest, you need per-user enforcement at the API boundary.

How to tag AI requests with an end user ID

To enforce user-level limits, the gateway must know which end user is making the call. You can provide this identifier through the OpenAI SDK, direct HTTP headers, or the @vibiz/app package. Always use a stable pseudonymous string, such as a database user ID, rather than an email address.

Using the OpenAI SDK

The OpenAI chat completions endpoint accepts a top-level user string:

TypeScript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: process.env.VIBIZ_AI_BASE_URL,
  apiKey: process.env.VIBIZ_AI_API_KEY,
});

const response = await openai.chat.completions.create({
  model: 'vibiz/fast',
  messages: [{ role: 'user', content: 'Summarize our onboarding steps.' }],
  user: 'usr_98a7f6c2',
});

console.log(response.choices[0]?.message.content);

Using @vibiz/app

If your backend uses @vibiz/app, call vibiz.user(id) to scope requests to that user:

TypeScript
import { vibiz } from '@vibiz/app';
import OpenAI from 'openai';

const userClient = vibiz.user('usr_98a7f6c2');
const openai = new OpenAI(userClient.ai);

const res = await openai.chat.completions.create({
  model: 'vibiz/smart',
  messages: [{ role: 'user', content: 'Draft a project proposal.' }],
});

Using vibiz.user(id) automatically sets the downstream headers for AI requests, actions, and custom events.

Using HTTP and curl

For raw HTTP requests or custom integrations, provide the user field in the JSON payload or pass the X-Vibiz-User header:

Terminal
curl https://thelastapi.dev/v1/ai/chat/completions \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "X-Vibiz-User: usr_98a7f6c2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vibiz/fast",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

How to configure the per-user daily budget

Project settings determine the maximum dollar amount any individual user can spend in a single UTC day. You can update this using the AI configuration endpoint.

Send a PATCH request to /v1/projects/:id/ai with your project ID and the desired end_user_daily_budget_usd value:

Terminal
curl -X PATCH https://thelastapi.dev/v1/projects/prj_123/ai \
  -H "Authorization: Bearer $OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_budget_usd": 25.00,
    "end_user_daily_budget_usd": 1.50
  }'

In this example, the entire project has a $25.00 daily cap, but no single end user can spend more than $1.50 within the same UTC day.

You can also inspect or adjust daily budgets with the CLI:

Terminal
vibiz ai budget 25 --project prj_123

Setting end_user_daily_budget_usd ensures that even if an end user attempts thousands of high-token completions using expensive models like vibiz/pro (Claude Opus 5.5 at $4/$20 per million tokens) or vibiz/smart (Claude Sonnet 5.5 at $2/$10 per million tokens), their individual spend halts the moment they reach $1.50.

Handling budget errors in your application

When an end user hits their limit, the gateway refuses subsequent AI requests from that user ID with an HTTP status 429 (rate_limited).

The returned JSON adheres to the standard OpenAI error format:

JSON
{
  "error": {
    "code": "rate_limited",
    "message": "Daily budget exceeded for this user.",
    "type": "requests",
    "param": null,
    "details": {
      "reason": "end_user_budget"
    }
  }
}

Catch this error in your application and return a clear status to your interface rather than a generic server error:

TypeScript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: process.env.VIBIZ_AI_BASE_URL,
  apiKey: process.env.VIBIZ_AI_API_KEY,
});

try {
  const completion = await openai.chat.completions.create({
    model: 'vibiz/fast',
    messages: [{ role: 'user', content: 'Generate sample data.' }],
    user: 'usr_98a7f6c2',
  });
} catch (err: any) {
  if (err.status === 429 && err.error?.details?.reason === 'end_user_budget') {
    // Inform the specific user that their daily AI quota has been reached
    console.warn('User has hit their daily allocation.');
  } else {
    throw err;
  }
}

If a user makes a streaming request mid-generation and exceeds a spend threshold, the error arrives as a final Server-Sent Events (SSE) data payload: data: {"error": {...}} without a terminating [DONE] marker.

How spending limits stack up

User budgets operate inside two broader safety limits provided by the platform. Every billable call must pass all three layers to execute.

Limit layerDefault valueConfigured viaRefusal code and reason
Account Safety Cap$5.00 per UTC day across AI and actionsConsole ▸ Billing, or PATCH /v1/billing {"daily_spend_limit_usd": 50}429, details.reason: "daily_spend"
Project AI Budget$1.00 per UTC day per projectConsole ▸ project ▸ AI, or PATCH /v1/projects/:id/ai {"daily_budget_usd": 10}429, details.reason: "project_budget"
End User AI Budgetnull (disabled until set)PATCH /v1/projects/:id/ai {"end_user_daily_budget_usd": 1.50}429, details.reason: "end_user_budget"

All daily counters reset automatically at midnight UTC (00:00:00Z).

Beyond spend caps, each call's worst-case cost (calculated using max_tokens at the model's list price) must fit within the account's prepaid balance plus a $0.50 buffer. If the balance cannot cover that worst case, the API refuses the call with a 402 payment_required error (insufficient_balance). To read more about managing credit limits, see Billing and credits.

Tracking spend per user with CLI and API

You can inspect per-user usage at any time to verify spend distribution or find out which users consume the most resources.

In the terminal, run:

Terminal
vibiz usage --by end_user --project prj_123

You can also filter by a specific user across a defined time period:

Terminal
vibiz usage --period 7d --end-user usr_98a7f6c2

Using HTTP, query the Usage and limits API endpoint:

Terminal
curl "https://thelastapi.dev/v1/usage?period=24h&group_by=end_user" \
  -H "Authorization: Bearer $VIBIZ_API_KEY"

The returned object lists cost_usd, billed_usd, token counts, and request counts grouped by each unique end_user value passed during that window. If any requests were sent without a user identifier, they appear grouped under unattributed.

Practical strategies for controlling user costs

Budgets stop runaways, but model choice determines how far each user's allowance stretches:

  1. Route basic tasks to cheaper models: Set your default chat model to vibiz/fast (GPT-6 Luna at $0.10/$0.50 per million tokens) or vibiz/lite (DeepSeek V4.1 Flash at $0.14/$0.42 per million tokens). Reserve higher-cost options like vibiz/pro for operations that genuinely require them. For an overview of model selection, read how to cut your LLM API bill.
  2. Constrain token ceilings: The API sets max_tokens to 1,024 by default (up to 16,384 maximum). Lowering max_tokens in your client calls reduces the worst-case balance reservation for each request.
  3. Guard autonomous execution: If you allow client-driven agent loops, combine per-user limits with tool-level monitoring. See how to stop an AI agent from overspending for techniques on scoping autonomous tasks.
  4. Switch models without refactoring: You can test different pricing tiers using one API key for GPT, Claude and Gemini by swapping the model parameter across lab IDs like moonshotai/kimi-k3.1-pro or stable platform aliases.

To configure your project's per-user AI limits, inspect your current usage using vibiz usage --by end_user or visit the settings page in your console. Create your account at thelastapi.dev/start to get started on the platform.

Frequently asked questions

What identifier should I use for the user parameter?

Pass a stable, pseudonymous internal user ID (such as a database primary key like usr_123). Never pass raw emails, phone numbers, or personally identifiable information in the user field.

When do per-user daily budgets reset?

All daily spend counters, including account caps, project AI budgets, and end-user daily budgets, reset at midnight UTC (00:00:00Z).

What happens if an API call does not supply a user identifier?

Calls made without a user parameter or X-Vibiz-User header execute against the project's daily AI budget and the account safety cap, but they bypass the per-user budget and appear as unattributed in usage reports.

Can an AI agent or Limited key change the per-user budget?

No. Modifying project AI budgets or billing caps requires owner privileges, meaning either an account console session or a full-access API key (access: owner).