# Budgets & limits How PrivateMind enforces spend and usage limits across API keys, users, and organizations. PrivateMind limits spend and usage at three levels: **per-API-key**, **per-user** and **per-organization**. As an org admin you can watch your organization's usage, set each member's monthly budget if you meter by cost, and export spend to charge it back. ## Organization limits You manage org limits from `/settings/org/overview` and `/settings/org/chat-usage`. What you see depends on whether your organization meters usage by tokens or by cost. ### Token-based organizations The Overview page at `/settings/org/overview` shows: - **Token limit / user / month**: a badge on the Token Usage card - **Total Tokens (this month)**: sum across the org for the current calendar month - **Avg Tokens / User**: total divided by user count - **Org Allocation Used**: percentage with a progress bar - **Top Users by Token Usage**: table with each user's tokens and their share of the per-user cap A warning appears when the allocation reaches 90%. Usage above the cap is throttled with standard HTTP rate-limit responses (see [Rate limits & budgets](https://docs.privatemind.com/rate-limits.html)). To raise the per-user token cap, ask your PrivateMind account contact. The org admin pages can't change it. ### Cost-based organizations If your org meters by cost, the Overview page shows cost in place of tokens. Every API call and chat message is priced at the model's input and output rates, and the cost is recorded against the user who made it. The **Usage** page at `/settings/org/chat-usage` is the cost dashboard. It has three tabs: - **Overview**: total spend, total budget, count of users over budget, top spenders chart - **Users & Budgets**: every user's monthly budget, current spend, percent used, and an Edit action - **Models**: usage broken down by model with token and cost totals #### Exporting usage to CSV **Export** on the Usage page downloads a CSV for the period selected on the dashboard. The file is named `chat-usage___.csv` and opens in any spreadsheet. Use it to reconcile spend offline, add figures to an internal report or, most often, **charge AI usage back to the user, team or cost centre that incurred it**. The CSV has three sections, one after another: 1. **Usage over time**: one row per day (or per week for longer windows) with requests, input tokens, output tokens, total tokens, and cost for that bucket. 2. **Usage by model**: one row per model id, with the same columns, for the whole period. 3. **Usage by user**: one row per user for the whole period. Use the **Usage by user** section to allocate cost. Its columns are: | Column | Meaning | | --- | --- | | User | The member's display name (falls back to their email, then their id, if a name isn't set). | | Email | The member's email address. | | Requests | Number of chat and API calls the user made in the period. | | Input Tokens | Tokens the user sent (prompts). | | Output Tokens | Tokens the models generated for the user. | | Total Tokens | `Input Tokens + Output Tokens`. Rows are sorted by this column, highest first. | | Cost (USD) | The user's spend for the period. | This section lists **every** user who was active in the period, so its totals add up to the org's full spend. The dashboard's "top users" panel shows only the top 20. **Application keys** belong to the org and run automations or service integrations. Their traffic is combined into one row labelled **Application keys**, with a blank Email cell. That way no person is charged for a shared service's spend, and each person's line shows only their own usage. If your organization is on **dedicated infrastructure**, you are metered by tokens, so the export leaves out the `Cost (USD)` column in every section and keeps the token columns. > [!TIP] > On a busy org, a very large window can hit a limit on how much detail the export reads in one pass. The export then adds a `Note` row, and the per-model and per-user figures may be slightly under-counted. The day-by-day **Usage over time** section is always exact. If you see the note, export a shorter window, month by month for example, to get figures you can reconcile to the cent. #### Editing a user's budget On the Users & Budgets tab, click a user's row, then **Edit Budget**, and enter a new monthly cap in dollars. The change applies as soon as you save: the user's next request is measured against the new cap. > [!WARNING] > If you lower a user's budget below what they've already spent this month, their next call fails with `402` until the monthly reset. Nothing is refunded. Tell the user before you cut a budget mid-month. #### Default budget for new members A new member gets your organization's default monthly budget when they first sign in. The default only sets the starting value: you can change anyone's cap on **Users & Budgets** at any time. #### What "monthly" means Budgets reset on the **first of each calendar month**, UTC. There is no rolling 30-day window. A budget you raise mid-month stays at the new value in the following months until you lower it. #### How spend is calculated A chat request costs `prompt_tokens × input_rate + completion_tokens × output_rate`. Embeddings bill input tokens only. Streamed and non-streamed responses cost the same, and for a stream the final `usage` block is what's billed. Spend is updated **after each request completes**, not while it runs. If you need finer tracking, measure it in your clients. See [Usage](https://docs.privatemind.com/usage.html) for the API-side view. ## Per-API-key budgets and rate limits The org-level budgets above cover chat-app users. API keys also have their own budgets and rate limits. [Rate limits & budgets](https://docs.privatemind.com/rate-limits.html) covers them from the developer's side. What an org admin needs to know: - **API keys belong to a user.** Their spend rolls up to that user's monthly total. - **Rate limits are per-key.** A user with two keys gets two requests-per-minute (RPM) windows. - **Budgets are per-key.** A user's overall spend is the sum of their keys' spend plus their chat-app spend, all measured against their monthly budget. Users create and manage their own keys at `/settings/api-keys`. An org admin can also create inference-only keys for members from a script with the [key management API](https://docs.privatemind.com/key-management-api.html). Those keys show in the member's own list with the admin's email on them. ## Limits in action When a user hits their budget or token cap: - API requests return `402 Payment Required` for a cost-based budget. It lasts until the budget is raised or the month rolls over. - API requests return `429 Too Many Requests` for rate limits and short-lived in-flight caps. These clear on their own: retry when the response's `Retry-After` says. A `429` needs nothing from you. - Chat messages in the app show an error that tells the user to ask their org admin. There is no automatic top-up. > [!TIP] > If one power user keeps hitting their cap, raise that user's budget first. Per-user changes take effect at once and you can reverse them. ## Where next - [Audit logs](https://docs.privatemind.com/audit-logs.html): every budget edit is logged with who, when, and the new value - [Rate limits & budgets](https://docs.privatemind.com/rate-limits.html): the developer-side reference for `402`, `429`, and per-key behaviour - [Usage](https://docs.privatemind.com/usage.html): the API endpoint for programmatic spend lookup - [My Usage](https://docs.privatemind.com/my-usage.html): the single-user view a member sees of their own spend