> 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/when-a-limit-is-reached.md).

# When a Limit Is Reached

Warn users before they run out, decide what they see when they do, and choose whether they can continue with a project code.

#### Warnings before the limit

Users get warnings as they approach their limit, so a block never comes as a surprise. Set this up in the **Alert Notifications** section of the Compute Blocks page.

**Channels**&#x20;

Enable any combination:

* **In-app banner:** a one-time, dismissable banner above the message box, colour-coded by threshold. It is informational only and does **not** block anything. For example: "You have used 90% of your Compute Block limit for this period."
* **Email the user who reaches the threshold:** sends the warning email to that user.
* **Email the selected admins:** also sends the warning email to the admins you pick under **Admin recipients**. Super admins can be picked too.

**Email content**&#x20;

Use **Edit email content** to customise the subject and body of the email.

**Thresholds**&#x20;

Define one or more thresholds at which warnings fire. For each threshold you set:

* **Percentage:** the share of the limit at which the warning triggers (for example 70% or 90%)
* **Colour:** the banner colour at that threshold (for example amber at 70%, red at 90%)
* **Banner / Email:** whether that threshold fires the banner, the email, or both

Use **Add threshold** to create more thresholds and **Remove** to delete one.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FDNzv0BBzWGCvQ07Z3SIf%2FScreenshot%202026-07-22%20at%2013.23.37.png?alt=media&#x26;token=442be156-2d96-4e8f-8f42-2dd0e119f26a" alt="" width="188"><figcaption></figcaption></figure>

{% hint style="info" %}
By default, two thresholds are configured: **70%** and **90%**, each firing both the banner and the email.
{% endhint %}

***

#### The check before each request

Before a request runs, Blockbrain estimates how many Compute Blocks it will need. If the estimate is more than the user has left, the request is not sent and the user sees **"Not enough Compute Blocks for this request"**, with the estimated amount and how many remain. A shorter message or a cheaper model usually fits.

This can happen before the limit is fully used up. It protects users from starting a long request that would fail halfway.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FKSIQ2VWB2at2bMS59yIY%2FScreenshot%202026-10-23%20at%2011.44.29.png?alt=media&amp;token=de7635c8-80b5-4688-a00d-8e1a24564033" alt="" width="375"><figcaption></figcaption></figure>

***

#### What happens at the limit

Once a user reaches their limit, every action that uses Compute Blocks is blocked:

* sending chat messages and running agents
* uploading or importing files in Knowledge Management, including the files inside a ZIP
* adding attachments
* generating notes or summaries
* memory
* text-to-speech
* exports

Files that are being processed when the limit is reached are marked "Out of compute blocks".

{% hint style="info" %}
Users can still freely **navigate** the platform. Only actions that consume Compute Blocks are blocked.
{% endhint %}

The user sees two things:

* a **popup** with your message, their limit and timeframe, and, if Extended Usage Amounts is on, a field for a project code
* a **banner** above the message box

The popup comes back whenever the user tries a blocked action.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2Fkm158jAalxWOFJFDKj7G%2FScreenshot%202026-07-22%20at%2013.40.27.png?alt=media&#x26;token=cd3717d3-1631-4c48-8c39-b0e64aa7586f" alt="" width="375"><figcaption></figcaption></figure>

**Customise the popup and the banner**

In the notification settings of the Compute Blocks page you can write your own texts. Use the **Limit type** switch to edit the soft limit and the hard limit versions separately:

* **Soft limit** texts show while users can still request extra Compute Blocks.
* **Hard limit** texts show when they cannot.

For each version you can set:

* **Popup Alert:** a **Title** and a **Message**. The user's limit and timeframe are added automatically.
* **Sendbox Banner:** the **Message** shown above the message box.

Leave a field empty to use the default text.

**Example message:**

{% hint style="info" %}
*"You have reached your usage limit. To request an increase, please contact* [*admin@yourcompany.com*](mailto:admin@yourcompany.com)*."*
{% endhint %}

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FJiYGUCydbtBV6pXznoNH%2FScreenshot%202026-10-23%20at%2011.45.19.png?alt=media&amp;token=81bfc5de-87dd-40e7-964d-afbe591e4130" alt=""><figcaption></figcaption></figure>

***

#### Letting users continue

**Extended Usage Amounts**

The **Extended Usage Amounts** toggle decides whether users can request more Compute Blocks when they reach a limit. In other words, it switches between a soft limit and a hard limit.

**To configure:**

1. Open the **Compute Blocks** page in Admin.
2. Find the **Extended Usage Amounts** toggle.
3. Turn it on or off.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FOqKsldkPb2QShluRenhA%2FScreenshot%202026-08-28%20at%2015.11.07.png?alt=media&#x26;token=d2531de2-312a-45c6-9fe1-dbc397a92bf7" alt=""><figcaption></figcaption></figure>

| Toggle  | Limit type | What the user can do at the limit                                                                                                                              |
| ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **On**  | Soft limit | Pick an amount of extra Compute Blocks, enter a project code, and continue immediately. When that extra amount is used up or expires, the limit applies again. |
| **Off** | Hard limit | Nothing. The user has to ask an admin, who raises the limit. Access is restored immediately after the admin saves.                                             |

{% hint style="info" %}
This toggle applies to user limits, bot limits, and cost center validation at the same time.
{% endhint %}

**Preset amounts and max requests**

Two settings control how much users can add:

* **Preset amounts:** the amounts of extra Compute Blocks users can choose from in the popup ("Choose extra Compute Blocks"). Set 1 to 5 whole numbers with **Edit Amounts**.
* **Max requests per period:** how many times a user can extend their limit with a project code in one period. Set it with **Edit Limit**. Enter a large number to make it practically unlimited.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FA3bTqAlWis8QVDlUAozY%2FScreenshot%202026-10-23%20at%2011.46.13.png?alt=media&amp;token=4aa1525e-d3df-4210-bb3d-d9f46745c1b3" alt=""><figcaption></figcaption></figure>

**Project code guidance**

Add your own text that tells users which project code or cost center to enter. It appears in the help tooltip next to the project code field. If you leave it empty, a default text is shown: "Enter the project code or cost center this extra usage should be billed to."

Set it under **Project Code Guidance** in the notification settings.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FkTEQkYix6IQKdHjXWEdF%2FScreenshot%202026-10-23%20at%2011.53.35.png?alt=media&amp;token=d0ea67ff-3ebc-42b0-b3b6-63772333e9b6" alt=""><figcaption></figcaption></figure>

***

#### Bots at their limit

**What users see.** In a chat with a capped public bot, the header shows a **Bot Compute Block usage** indicator. As the bot nears its cap, users see a banner such as "This bot has used 90% of its Compute Block limit for this period." At the cap:

* With a hard limit, the bot stops answering until its period resets or an admin raises the cap.
* With a soft limit, users can choose an amount of extra Compute Blocks and enter a project code to continue. The extra amount is added to the bot's pool and shows in the Bot tab of Project Codes.

**Bot alert notifications.** To warn admins before a bot runs out, open the **Bots** tab in Limits Overrides and click **Configure notifications**. You can:

* turn on **Email admins when a threshold is reached**
* choose the **Admin recipients**
* write the **Email subject** and **Email body**

#### Cost Center Validation

By default the project code field accepts any text. Cost Center Validation restricts it to **valid codes only**, so cost attribution stays accurate.

Choose one of three modes:

<details>

<summary><strong>No validation (default)</strong></summary>

The field stays free-text. Any value the user types is accepted.

</details>

<details>

<summary><strong>Stored Codes (codes kept in Blockbrain)</strong></summary>

Blockbrain keeps a copy of your code list. The field becomes a **searchable dropdown**, so users pick from your codes instead of typing.

**Import a file.** Click **Import**, choose a CSV or JSON file, check the preview, and confirm.

* **CSV:** a header row with a required `code` column and an optional `label` column. Wrap a value in double quotes if it contains a comma.
* **JSON:** an array of objects, or an object with a `codes` array. Each object needs `code`, and `label` is optional.
* Use **Download template** for a ready-made file. The maximum size is 5 MB.
* The preview marks every row as **New**, **Update**, **Duplicate in file**, or **Error**, and tells you how many were written after the import.

**Manage the list.** The list shows **Code**, **Label**, **Status** and **Added**. **Deactivate** a code to stop it being accepted, and **Activate** it to allow it again. Both work on one code or on a selection.

**Keep it in sync automatically.** Instead of importing files, your own systems can add and remove codes through the Cost Center Admin API whenever a project opens or closes. API key authentication is supported. See Cost Center Admin API.

</details>

<details>

<summary><strong>Remote API (your own API checks each code)</strong></summary>

Blockbrain asks your own API about every code a user submits. No copy of your code list is stored in Blockbrain. The field stays free-text, and the code is checked when the user leaves the field and when they submit.

Set up the call in the **Remote API** section:

| Section              | What you set                                                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**         | **Base URL** (for example `https://api.example.com`), **Method** (GET or POST), and **Path** (for example `/validate`)                                                                                          |
| **Value placement**  | Where the code goes: **Request body**, **Query string**, **URL path**, or **Header**. For the body, a dotted **Value path**: `code` sends `{ "code": "PC-01" }`.                                                |
| **Authentication**   | **None**, **Bearer token**, **Basic** (username and password), or **Custom header**. Secrets are stored securely and never shown again.                                                                         |
| **Response mapping** | **Success status codes** (for example 200, 204), **Reject status codes** (for example 422), and optionally the **Valid field path**, **Valid equals** value, and **Error message path** to read from the answer |
| **Advanced**         | **Timeout**, **Retry attempts**, and **Retry delay**                                                                                                                                                            |

Before you save, use **Test validation**: enter a sample code and click **Run test**. You see whether it came back **Valid**, **Invalid**, or **Error**, the HTTP status, the time it took, the request that was sent, and the raw response. Nothing is saved by the test.

Then save and turn on **Enable remote validation**. **Clear config** deletes the endpoint and credentials and turns remote validation off. Your stored codes are not affected.

**If your API cannot be reached:**

| Policy                    | What happens                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| **Fail closed** (default) | The submission is blocked with a "cost center validation is temporarily unavailable" message. |
| **Fail open**             | The submission is allowed, and the skipped check is recorded so you can reconcile later.      |

To switch to fail open, contact your Blockbrain contact.

{% hint style="info" %}
Every check is a live call to your API. Results are not cached, so a code closed a minute ago on your side is rejected on the very next submission.
{% endhint %}

</details>

***

#### Project Codes

Every time someone enters a project code to get more Compute Blocks, it shows up in the **Project Codes** view, one row per request. There are two tabs:

* **User:** extra Compute Blocks users added to their own allowance
* **Bot:** extra Compute Blocks added to a public bot's pool

| Column                                   | Description                                            |
| ---------------------------------------- | ------------------------------------------------------ |
| **Project code**                         | The code that was entered                              |
| **First name**, **Last name**, **Email** | Who made the request (User tab)                        |
| **Bot** and **Requester**                | Which bot got the extra amount and who asked (Bot tab) |
| **Granted**                              | The number of extra Compute Blocks granted             |
| **Used**                                 | How many of them have been used                        |
| **Status**                               | **Active** or **Expired**                              |
| **Requested**                            | When the request was made                              |
| **Expires**                              | When the extra amount expires                          |

You can **search by project code** and **filter by date range** (From / To). Click **Export** to download the list as CSV, XLSX, or JSON. If there are too many rows, narrow the date range or the project code and try again.

<figure><img src="https://3232460952-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIabFtGTeQzwfWCzp8vd6%2Fuploads%2FbOweMRKff678dGovv1wr%2FScreenshot%202026-07-22%20at%2013.35.55.png?alt=media&#x26;token=77d0c5a0-3751-4b39-bc4c-e6736f713e3c" alt=""><figcaption></figcaption></figure>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blockbrain.ai/for-admins/cost-control/when-a-limit-is-reached.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
