Managing User AI Credit Budgets

Once an instance pool has been topped up (see Buying AI Credits), instance admins can hand out personal AI credit budgets to individual users. This is what powers the per-connection budget source — a user with their own per-instance budget can switch a connection to bill that budget instead of their home pool.

This page covers the User Budgets tab on /billing-credits (Manage → AI Credits → User Budgets).

Who can use this

You must be an Instance Admin of the currently selected instance.
The User Budgets tab only operates on the instance shown in the header. To manage another instance, switch it on the home screen and re-open Manage → AI Credits.

What the table shows

Every user that has a connection to this instance appears as a row, with:

User — display name and email. A small home icon marks the user's home instance.
Balance — the user's current personal AI credit balance (shared across all instances they use).
This month — credits topped up to this user from this instance's pool in the current calendar month.
Monthly limit — the cap on how many credits you can transfer from this pool to this user per month. Empty means no cap.
Auto top-up — Off, or threshold → ceiling when enabled.

Use the search box to filter by name or email.

Top up a user manually

Open the row's ⋯ menu and pick Top up now….

Source instance — the instance pool you are funding the top-up from (the active one).
Credits to add — how many credits to move from the pool into the user's personal balance.
Note — optional, free-text reason. Visible later in the top-up history.

The dialog blocks the action when:

The pool has fewer credits than you're trying to send.
The amount would exceed this user's monthly limit on this instance.

On success, the user's balance updates immediately and an entry is written to their top-up history.

Set a monthly limit

Open the row's ⋯ menu and pick Edit settings…, then fill in Monthly top-up limit (credits).

The limit is enforced per calendar month, per (user, instance) pair.
Manual top-ups and auto top-ups both count against this limit.
Leave the field empty to remove the cap entirely.

The dialog shows how much you've already used this month so you can size the cap sensibly.

Set a daily usage limit

Open Edit settings… and fill in Daily usage limit (credits) to cap how much a user can spend on this instance in a single day.

Whole credits only. Leave the field empty to remove the cap entirely.
It caps the sum of AI-credit usage by that user on this instance within one UTC day, and it is independent of the user's remaining balance — a user with credits to spare can still hit the daily cap.
It is checked at the start of each new conversation turn. A long-running task that has already started (including background automations mid-flight) is allowed to finish so partial work is never lost.
When a user hits the cap:
- The next message they send in any conversation on this instance ends immediately with a chat reply explaining the situation.
- They also receive a notification, so background runs and unattended sessions surface the reason.
- The cap resets at 00:00 UTC.

Example: setting a daily limit of 200 for a user means the operator refuses to start new turns once their same-day usage on this instance reaches 200 credits, even if they still have thousands in their personal balance.

Configure auto top-up

In the same Edit settings… dialog, switch Auto top-up on and set:

Threshold — when the user's balance drops below this number of credits, an auto top-up fires.
Ceiling — auto top-up tops the user up to this number. (It does not add a fixed amount — it brings the balance to the ceiling.)

Rules:

Ceiling must be greater than threshold.
Auto top-ups are funded from this instance's pool, so the pool needs enough credits at the time of the run.
Auto top-ups respect the monthly limit. If a top-up would breach the cap, it is skipped.
Auto top-ups run on a 10-minute cycle. They are not instant, so set the threshold high enough that a user will not run out before the next cycle picks them up.

Planning the threshold

Because auto top-ups are evaluated only every 10 minutes, the threshold is the safety margin, not the point at which you want the user to actually stop. Size it so the user cannot burn through the gap between threshold and zero in the time it takes for the next cycle to run, plus the time a long turn may already be in flight.

A good rule of thumb:

A single chat turn can easily cost 5–20 credits.
A saved-agent run or multi-step task can cost 30–100 credits.
App Builder sessions with many iterations can cost several hundred credits in a short window.

Pick a threshold that leaves enough headroom for the user's typical workload between cycles.

Recommended setups

Threshold → Ceiling	Best for	Why
50 → 100	Chat-only users	Minimum viable setup. Covers light chat use between 10-minute cycles without interrupting work.
100 → 200	Chat users who also run saved agents	Normal safety margin for mixed daily use — chat plus occasional agent runs.
200 → 400	Heavy App Builder users	Larger buffer for users who run long iterations or build apps, where individual turns can be expensive.

These are starting points. Monitor the user's actual burn rate in the top-up history and raise the threshold if they ever hit zero before an auto top-up fires.

Auto top-ups appear in the history with the Auto badge.

View top-up history

The ⋯ menu also has View history, which lists the most recent 100 top-ups for that user — across all instances you have visibility into:

Date, Type (Manual / Auto / Adjustment), Source instance, Credits, Balance after, Note.

Use it to audit who funded what and to investigate billing questions from your users.

How this ties into per-connection billing

A user's personal balance is the budget that the This instance option in My Connections → Edit Instance → AI credit budget draws from. The option only becomes selectable on a given instance once you, as that instance's admin, have topped the user up there. See AI Credit Budget per Connection for the user-side view.