> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/for-admins/cost-control.md). # Cost Control ### Glossary | Term | Definition | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Compute Block (CB)** | The unit that measures resource consumption on the platform. Every action - such as sending a chat message or uploading a file - consumes a defined number of CBs. | | **CB Limit** | The maximum number of Compute Blocks a user may consume within a given timeframe. | | **Timeframe** | The period over which CB consumption is counted and reset - either Daily, Weekly, or Monthly. | | **Hard Limit** | An enforcement mode where, once the CB limit is reached, no further CB-consuming actions are possible until an admin increases the limit. The user cannot self-service. | | **Soft Limit** | An enforcement mode where, once the CB limit is reached, the user is not fully blocked: they can enter a project code/cost center in the pop-up to grant themselves a temporary allowance of additional Compute Blocks and keep working. The extra usage is attributed to that code and expires after a set period. | | **Default Limit** | A system-wide CB limit that applies to all users unless an individual override is set. | | **Group Limit** | A CB limit applied to an entire Active Directory (AD) group, setting the same allowance for all members at once. | | **API Key Limit** | A CB limit enforced at the API key level, restricting how many Compute Blocks a given API key may consume within a timeframe. | | **Cost Center / Project Code** | An optional numeric label a user can enter so their usage can be attributed to an internal cost center, project, or case number (*Aktenzeichen*) for reporting. | | **Usage Warning** | A one-time, dismissable banner (and/or email) that appears before the hard limit is reached, alerting the user as they approach their allowance. | {% hint style="info" %} The feature is disabled by default. Administrators must turn in on in order to use the Compute Block Limit. {% endhint %}
### Admin Configuration #### Default CB Limit Administrators configure a **default user limit** that applies to all users globally. This limit consists of two parameters: | Parameter | Default Value | Available Options | | ------------------ | ------------- | ------------------------ | | **Compute Blocks** | 500.000 | Any custom numeric value | | **Timeframe** | Monthly | Daily / Weekly / Monthly | {% hint style="info" %} The default limit is the baseline for every user account. It takes effect unless an individual override is configured for a specific user. {% endhint %} *** #### **Limits Overrides (Users & Groups)** Overrides let admins depart from the default limit for specific users or entire groups. They are managed from the **Limits Overrides** area of the CB Limit admin page, which is organized into two tabs — **Users** and **Groups** — with a shared search bar and a **New Override** action. Both tabs support inline editing, bulk actions, and pagination. **Precedence (highest to lowest):** 1. **Per-user override** — always wins. 2. **Group limit** — applies to members of a limited group. If a user belongs to several limited groups, the **most generous** limit (highest daily-equivalent rate) applies. 3. **Default limit** — the global baseline. #### **Per-User Override** Admins can override the default limit for any individual user directly in **User Management**. Each user row exposes two editable columns: * **Compute Blocks** - the maximum CB allowance for that user * **Timeframe** - the reset period for that user's limit **To override a user's limit:** 1. Go to **User Management**. 2. Find the user in the list. 3. Edit the **Compute Blocks** and **Timeframe** values in that user's row. 4. Save your changes.
{% hint style="info" %} An individual user's limit always takes **precedence** over the global default limit. {% endhint %} *** #### Group Limit & Bulk User Updates Admins can apply CB limits to **multiple users at once** by targeting an **Active Directory (AD) group**. This eliminates the need for manual, one-by-one edits in User Management. **To set a limit for a group:** 1. Go to the **Groups** section in Admin. 2. Select the AD group you want to configure. 3. Set the **Compute Blocks** and **Timeframe** values for the group. 4. Save your changes — the limit is applied to all group members immediately. {% hint style="info" %} Individual user overrides still take **precedence** over group limits. Group limits take precedence over the global default. {% endhint %} | Parameter | Default Value | Available Options | | ------------------ | ------------- | ------------------------ | | **Compute Blocks** | 5,000,000 | Any custom numeric value | | **Timeframe** | Monthly | Daily / Weekly / Monthly | {% hint style="info" %} Group limits take precedence over the global default, but individual user overrides still take precedence over group limits. {% endhint %} #### CB Limit per API Key Admins can set and enforce CB limits at the **API key level**. This is the natural enforcement layer for API-based consumption and prevents individual keys from exceeding their allocated budget. **To set a limit for an API key:** 1. Go to **API Key Management** in Admin. 2. Select or create an API key. 3. Set the **Compute Blocks** limit and **Timeframe** for that key. 4. Save your changes. | Parameter | Default Value | Available Options | | ------------------ | ------------- | ------------------------ | | **Compute Blocks** | 5,000,000 | Any custom numeric value | | **Timeframe** | Monthly | Daily / Weekly / Monthly | {% hint style="info" %} API key limits operate independently of user limits. A user may still have capacity while their API key is blocked, or vice versa. {% endhint %} #### Custom Notification Message When a user hits their hard CB limit, a popup notification is displayed. Admins can define the **text content** of this message. The popup automatically includes: * The admin-defined message text * The user's assigned CB limit * The active timeframe **Example admin-defined message:** {% hint style="info" %} *"You have reached your usage limit. To request an increase, please contact* [*admin@yourcompany.com*](mailto:admin@yourcompany.com)*."* {% endhint %}
#### **Alert Notifications** Admins can warn users **as they approach their limit**, at configurable thresholds, via an **in-app banner** and/or **email**. This is configured in the **Alert Notifications** section of the Compute Block settings. **Channels** — enable any combination: * **In-app banner** — show a banner in the app when a threshold is reached. * **Email the user who reaches the threshold** — send the warning email to the affected user. * **Email the selected admins** — also send the warning email to chosen admins. **Admin recipients** — When admin emails are enabled, search for and select the admins who should also receive the warning email when a threshold is reached. **Email content** — Use **Edit email content** to customise the subject and body of the email sent to users and admins. **Thresholds** — Define one or more thresholds at which warnings fire. For each threshold you can set: * **Percentage** — the share of the limit at which the warning triggers (e.g. 70%, 90%) * **Colour** — the colour used for the banner at that threshold (e.g. amber at 70%, red at 90%) * **Banner / Email** — whether that threshold fires the in-app banner, the email, or both Use **Add threshold** to create additional thresholds and **Remove** to delete one.
{% hint style="info" %} By default, two thresholds are configured: **70%** and **90%**, each firing both the banner and email. {% endhint %} #### **Project Code / Cost Center Field Guidance** Admins can define **tenant-specific instructional text** for the **Project code / cost center** field shown in the limit-reached pop-up. This helps users understand exactly what to enter (for example, the expected format or which code to use), reducing incorrect submissions. * The guidance is set per tenant in the relevant admin setting. * It is displayed to the user without any additional interaction — shown as inline helper text below the field or as an improved placeholder. * If no custom text is defined, a default placeholder is shown.
#### **Project Codes** When a user reaches their CB limit, they can enter a **project code** in the limit pop-up to grant themselves additional Compute Blocks, attributed to that code. Admins can review all of these requests in the **Project Codes** view. {% hint style="info" %} Every extra Compute Block a user added by entering a project code appears here — one row per request. {% endhint %} Each row shows: | Column | Description | | ---------------- | -------------------------------------------------------------- | | **Project code** | The code the user entered when requesting extra Compute Blocks | | **User** | The user who made the request (name and email) | | **Granted** | The number of extra Compute Blocks granted for that request | | **Used** | How many of the granted Compute Blocks have been consumed | | **Status** | The current state of the grant (e.g. Active, Expired) | | **Requested** | When the request was made | | **Expires** | When the granted allowance expires | Admins can **search by project code** and **filter by date range** (From / To) to narrow the list.
#### **Usage Logging & Export** Usage is logged per session and can be exported as **CSV** from the **Admin Panel → Compute Block** section. The export gives admins a complete picture per user — their assigned limit, actual usage while below the limit, and any over-usage once the limit is exceeded (together with any cost center / project code the user entered).
*** #### Adjusting Limits CB limits can be updated at any time in **User Management** - both the default limit and individual user overrides. Changes take effect **immediately** upon saving. *** ### User-Facing Behavior #### Usage Visibility Users can monitor their CB consumption in their **User Profile**. Usage is displayed as a **progress bar**, showing: * Total CBs consumed in the current timeframe * The assigned CB limit *** #### **Early Usage Warnings** Before the CB limit is reached, users receive proactive warnings so a block never comes as a surprise. Warnings fire at admin-configured thresholds (**70%** and **90%** by default) and can be delivered as an in-app banner, an email, or both. * The **in-app banner** is a one-time, dismissable banner shown above the prompt window, colour-coded by threshold. It is informational only and does **not** block any actions. * The **email** notifies the user (and, optionally, selected admins) that the threshold has been reached. {% hint style="info" %} The specific thresholds, colours, and channels are set by your administrator (see **Alert Notifications**). {% endhint %} #### Limit Enforcement Once a user's CB limit is reached, the following behavior is triggered: 1. A **popup dialog** appears, displaying: * The administrator's custom message * The user's limit and timeframe * A field to enter a **project code / cost center number**, so the user's usage can be attributed to the correct cost allocation for reporting. The field shows instructional helper text to guide what to enter (admins can customise this text per tenant — see [#project-code-cost-center-field-guidance](#project-code-cost-center-field-guidance "mention")
2. By entering a project code and submitting, the user is **granted a set amount of additional Compute Blocks**, attributed to that code, which lets them continue working. The grant has an expiry, and its usage is tracked (admins can review all grants in the **Project Codes** view — see above). Closing the dialog without entering a code grants no additional allowance, and the standard limit behavior applies. 3. The dialog re-appears whenever the user attempts any **CB-consuming action** (*number of times a user can request more CBs is also configurable by the Admin*)— including sending a chat message, uploading or importing files in Knowledge Management, adding attachments, generating notes or summaries, text-to-speech, and exports. 4. Until additional Compute Blocks are granted (via a project code, or by an admin raising the limit), all CB-consuming actions are **blocked**. {% hint style="info" %} The user can still freely **navigate** the platform. Only actions that consume Compute Blocks are restricted. {% endhint %} *** #### Regaining Access How a user regains access depends on the enforcement mode: * **Soft limit:** the user can enter a project code in the pop-up to grant themselves a temporary allowance of additional Compute Blocks and continue working immediately. Once that allowance is used up or expires, the limit applies again. * **Hard limit:** the user **cannot self-service** an increase. They must contact an administrator and request a CB limit adjustment; once the admin increases the limit, access is **restored immediately**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.blockbrain.ai/for-admins/cost-control.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.