From 9df07686ad314ec5c059ce46048b4fb7915771f5 Mon Sep 17 00:00:00 2001
From: Olivier Bossel <olivier.bossel@gmail.com>
Date: Mon, 9 Feb 2026 13:05:52 +0100
Subject: [PATCH] docs: add per model specs doc and example

---
 pages/docs/configuration/token_usage.mdx | 26 ++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/pages/docs/configuration/token_usage.mdx b/pages/docs/configuration/token_usage.mdx
index 58da424c0..e68bab12c 100644
--- a/pages/docs/configuration/token_usage.mdx
+++ b/pages/docs/configuration/token_usage.mdx
@@ -67,6 +67,32 @@ balance:
 
 Check out the [Balance Configuration](/docs/configuration/librechat_yaml/object_structure/balance) page for more details.
 
+## Per `modelSpecs` Balance
+
+In addition to the global balance settings, you can also configure token credit limits on a per-model-spec basis using the `modelSpecs` object in your `librechat.yaml` file. This allows for more granular control over token usage for specific models.
+
+```yaml filename="librechat.yaml"
+version: 1.2.8
+
+modelSpecs:
+  list:
+    - name: "my-nice-model-spec"
+      label: "My Nice Model Spec"
+      description: "Most beautiful model spec ever"
+      group: "My Models"
+      balance: {
+        enabled: true # <===============
+        startBalance: 10000
+        autoRefillEnabled: false
+        refillIntervalValue: 1
+        refillIntervalUnit: 'days'
+        refillAmount: 100
+      },
+      preset:
+        endpoint: "azureOpenAI"
+        model: "gpt-4.1"
+```
+
 ## How Auto-Refill Works
 
 When a user's balance is tracked and **autoRefill** is enabled, the system will automatically add credits to the balance only when the specified time interval has passed since the last refill. This is achieved by comparing the current date with the `lastRefill` date plus the specified interval.