# 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.

**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](https://thelastapi.dev/blog/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:

```ts
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:

```ts
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:

```bash
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](https://thelastapi.dev/docs/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:

```bash
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:

```bash
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:

```ts
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 layer | Default value | Configured via | Refusal code and reason |
| --- | --- | --- | --- |
| **Account Safety Cap** | $5.00 per UTC day across AI and actions | Console ▸ Billing, or `PATCH /v1/billing {"daily_spend_limit_usd": 50}` | `429`, `details.reason: "daily_spend"` |
| **Project AI Budget** | $1.00 per UTC day per project | Console ▸ project ▸ AI, or `PATCH /v1/projects/:id/ai {"daily_budget_usd": 10}` | `429`, `details.reason: "project_budget"` |
| **End User AI Budget** | `null` (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](https://thelastapi.dev/docs/billing).

## 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:

```bash
vibiz usage --by end_user --project prj_123
```

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

```bash
vibiz usage --period 7d --end-user usr_98a7f6c2
```

Using HTTP, query the [Usage and limits](https://thelastapi.dev/docs/usage) API endpoint:

```bash
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](https://thelastapi.dev/blog/cut-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](https://thelastapi.dev/blog/stop-ai-agent-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](https://thelastapi.dev/blog/one-api-key-gpt-claude-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](https://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).

---

Published 2026-11-15 · https://thelastapi.dev/blog/per-user-ai-budgets
