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.