docs: periodic token budget reset & guardrail member budgets

v3/general/custom-api-keys.mdx

@@ -14,7 +14,7 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx";
   proficiencyLevel="Intermediate"
   keywords={["Eden AI", "AI API", "rate limits", "billing", "monitoring"]}
   datePublished="2026-05-06T00:00:00Z"
-  dateModified="2026-05-07T00:00:00Z"
+  dateModified="2026-07-21T00:00:00Z"
 />
 
 Custom API keys let you create additional tokens beyond your main account key. Each token can have its own budget, expiration, and type, giving you fine-grained control over access and spending.
@@ -122,6 +122,66 @@ curl -X POST https://api.edenai.run/v2/user/custom_token/ \
 
 When `active_balance` is `true`, every API call deducts from the token's balance. Once it reaches $0, the token stops working.
 
+## Periodic Budget Reset
+
+A budget can either **reinitialize automatically** each day, week, or month, or be a **one-time** allowance that stays at $0 once spent until you top it up manually. You control this with `balance_reset_period` (the reset frequency) and `balance_reset_amount` (the amount the balance is restored to at the start of each period).
+
+### In the dashboard
+
+On the [API Keys](https://app.edenai.run/settings/api-keys) page, create or edit a key and turn on **Spending Limit**. Set the **Reset allowance** (the amount restored each period) and choose a **Resets** frequency — **Daily**, **Weekly**, **Monthly**, or **Never**. A reset frequency is always selected when a spending limit is on; it defaults to **Monthly**. Choose **Never** for a one-time budget that does not renew. A separate **Current balance** field shows what's available right now; editing the allowance only takes effect at the next reset.
+
+### Through the API
+
+<CodeGroup>
+```python Python
+import requests
+
+headers = {
+    "Authorization": "Bearer YOUR_API_KEY",
+    "Content-Type": "application/json"
+}
+
+response = requests.post(
+    "https://api.edenai.run/v2/user/custom_token/",
+    headers=headers,
+    json={
+        "name": "team-daily",
+        "token_type": "api_token",
+        "balance_reset_amount": "10.00",
+        "balance_reset_period": "daily"
+    }
+)
+```
+
+```bash cURL
+curl -X POST https://api.edenai.run/v2/user/custom_token/ \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "team-daily",
+    "balance_reset_amount": "10.00",
+    "balance_reset_period": "daily"
+  }'
+```
+</CodeGroup>
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `balance_reset_period` | `none`, `daily`, `weekly`, `monthly` | How often the balance is restored. `none` = one-time budget; it is the default when the field is omitted from the API request. (The dashboard instead pre-selects **Monthly** when you enable a spending limit.) |
+| `balance_reset_amount` | positive amount | The value the balance is reset to each period. Required whenever the period is not `none`. |
+
+Behaviour to know:
+
+- Setting a reset period **automatically enforces the budget** (`active_balance` becomes `true`) — you don't have to set it separately.
+- `balance_reset_amount` is the reset **target**, kept separate from the live `balance` (the amount remaining right now). They are not the same field.
+- A new periodic token **starts the period full**: if you don't pass a starting `balance`, it begins at `balance_reset_amount`. Passing an explicit `balance` lets a key start partway through a period.
+- Resets run at **midnight Europe/Paris time**: daily every night, weekly on Monday, monthly on the 1st.
+- Setting the period back to `none` clears `balance_reset_amount` and returns the token to a one-time budget.
+
+<Note>
+This per-token reset is distinct from the **per-member budget cap** you can set on a [guardrail](/v3/organization/guardrails#budget-cap). A token budget is a hard cap on one key (it stops at $0); a member budget is a soft periodic spend cap that follows a person across all their keys.
+</Note>
+
 ## List All Tokens
 
 <CodeGroup>
@@ -155,6 +215,7 @@ Use clear naming conventions like `env-project-purpose` (e.g., `prod-billing-api
 </Tip>
 
 - **Set budgets on non-production tokens** to prevent accidental overspending during development.
+- **Use a periodic reset** (`balance_reset_period`) for recurring allowances — e.g. a $10/day CI key — instead of topping up manually.
 - **Use sandbox tokens for CI/CD** to validate integrations without incurring costs.
 - **Rotate tokens periodically** — create a new token, migrate your application, then delete the old one.
 - **Set expiration dates** on temporary tokens (e.g., for contractors or short-term projects).

v3/organization/guardrails.mdx

@@ -1,28 +1,29 @@
 ---
 icon: "shield-check"
 title: "Guardrails"
-description: "Guardrails are reusable usage policies that control which models your team can call and how often. Create them in the dashboard and attach them to roles, members, or API tokens."
+description: "Guardrails are reusable usage policies that control which models your team can call, how often, and how much a member can spend. Create them in the dashboard and attach them to roles, members, or API tokens."
 ---
 import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx";
 
 <TechArticleSchema
   title={"Guardrails"}
-  description={"Guardrails are reusable usage policies that control which models your team can call and how often. Create them in the dashboard and attach them to roles, members, or API tokens."}
+  description={"Guardrails are reusable usage policies that control which models your team can call, how often, and how much a member can spend. Create them in the dashboard and attach them to roles, members, or API tokens."}
   path="v3/organization/guardrails"
   articleSection="Organization"
   about={"Access Control"}
   proficiencyLevel="Intermediate"
-  keywords={["Eden AI", "guardrails", "usage policy", "access control", "rate limits", "model restrictions"]}
+  keywords={["Eden AI", "guardrails", "usage policy", "access control", "rate limits", "model restrictions", "budget cap", "spending limit"]}
   datePublished="2026-06-11T00:00:00Z"
-  dateModified="2026-06-11T00:00:00Z"
+  dateModified="2026-07-21T00:00:00Z"
 />
 
-A **guardrail** is a reusable usage policy that controls two things:
+A **guardrail** is a reusable usage policy that controls:
 
 - **Model access**: which providers and models can be called.
 - **Rate limits**: how many requests can be made over a given period.
+- **Member budget**: a spending cap for a member over a period (see [Budget cap](#budget-cap)).
 
-You create a guardrail once, then attach it to a **role**, a **member**, or an individual **API token**. For example, one team can be limited to a curated set of models, or a shared token can be capped to a low request rate.
+You create a guardrail once, then attach it to a **role**, a **member**, or an individual **API token**. For example, one team can be limited to a curated set of models, a shared token can be capped to a low request rate, or a member can be given a monthly spending cap.
 
 <Note>
 Guardrails are part of the advanced organisation features. See [plans and pricing](https://www.edenai.co/pricing) for availability.
@@ -43,6 +44,9 @@ In the **Rate Limit** field, enter a limit in the form `N/period`, for example `
 <Step title="Restrict models (optional)">
 Turn on **Enable model rules** to control which models can be used, then define your allow/deny rules. See [Model rules](#model-rules) below.
 </Step>
+<Step title="Set a member budget (optional)">
+Enter a **Budget** amount and a **period** (daily, weekly, or monthly) to cap how much a member can spend. See [Budget cap](#budget-cap) below.
+</Step>
 <Step title="Save">
 Click **Create Guardrail**. It now appears in your guardrails list, ready to assign.
 </Step>
@@ -83,6 +87,28 @@ The rate limit uses the format `N/period`, where `period` is `second`, `minute`,
 
 Leave the rate limit empty on a guardrail to inherit it from the next level up (role → organisation default).
 
+## Budget cap
+
+A guardrail can cap how much a **member** spends over a recurring period. In the **Create/Edit Guardrail** dialog, turn on **Member budget** ("Cap each member's spend across all their API keys"), then set a **Budget** amount (in USD) and a **Per** period:
+
+| Period | Window |
+| --- | --- |
+| `daily` | Resets each day |
+| `weekly` | Resets each week |
+| `monthly` | Resets each month |
+
+Both fields are set together — a budget needs a period, and a period needs an amount. Leave them empty to apply no spend cap.
+
+How it behaves:
+
+- **Per member, not shared.** The cap applies to each member the guardrail resolves to individually — it is not a shared pool across the team.
+- **Soft cap.** The check happens before each request. A request already in flight can push spend past the cap; the *next* request is the one that gets blocked. The limit is a spending guardrail, not a hard cutoff mid-request.
+- **Counts real usage only.** [Sandbox](/v3/general/sandbox) calls and calls made with your own provider keys ([BYOK](/v3/general/byok)) don't count toward the budget. Refunds credit it back.
+
+<Note>
+The budget only applies when a guardrail is attached to a **role** or a **member**. A budget set on a guardrail that is attached to an **API token** is ignored — use a [token budget](/v3/general/custom-api-keys) to cap a single key instead.
+</Note>
+
 ## Assigning a guardrail
 
 A guardrail does nothing until it's attached to something. You can assign it to:
@@ -97,7 +123,9 @@ When a request comes in, Eden AI resolves the policy **per field, most specific
 token  →  member  →  role  →  organisation default
 ```
 
-For each setting (model rules and rate limit) independently, Eden AI uses the value from the most specific level that has it set, and inherits the rest. So a token can override the model rules while still inheriting its role's rate limit.
+For **model rules** and **rate limit** independently, Eden AI uses the value from the most specific level that has it set, and inherits the rest. So a token can override the model rules while still inheriting its role's rate limit.
+
+The **member budget** resolves differently: only the **member** and **role** levels are considered (token budgets are handled separately, on the token itself), and the budget amount and period are always taken together from the most specific level that sets them — they are never mixed across levels.
 
 <Note>
 Guardrails can also be managed programmatically through the User Management API if you need to automate provisioning. See the [API Reference](https://www.edenai.co/docs) for the `guardrails` endpoints.
@@ -106,5 +134,5 @@ Guardrails can also be managed programmatically through the User Management API
 ## Related
 
 - [Users & Organisation](/v3/organization/users-organisation): roles, permissions, and members.
-- [Custom API Keys](/v3/general/custom-api-keys): per-token budgets that pair well with per-token guardrails.
+- [Custom API Keys](/v3/general/custom-api-keys): per-token budgets, which cap a single key rather than a member.
 - [Rate Limits](/v3/overview/rate-limits): how default rate limiting works.

v3/organization/users-organisation.mdx

@@ -14,7 +14,7 @@
   proficiencyLevel="Intermediate"
   keywords={["Eden AI", "AI API", "RBAC", "roles", "permissions", "organisation"]}
   datePublished="2026-06-11T00:00:00Z"
-  dateModified="2026-06-11T00:00:00Z"
+  dateModified="2026-07-21T00:00:00Z"
 />
 
 Eden AI provides team and organisation management features for companies that need structured access control, role-based permissions, and governance over their AI usage.
@@ -62,13 +62,13 @@
 
 ## Guardrails
 
-Beyond who can manage the organisation, you can control **which models members can call and how often** using [guardrails](/v3/organization/guardrails): reusable usage policies that combine model/provider access rules with rate limits. Guardrails can be attached to a role, an individual member, or a single API token, and resolve most-specific-first (token → member → role → organisation default).
+Beyond who can manage the organisation, you can control **which models members can call, how often, and how much they can spend** using [guardrails](/v3/organization/guardrails): reusable usage policies that combine model/provider access rules, rate limits, and per-member budget caps. Guardrails can be attached to a role, an individual member, or a single API token. Model rules and rate limits resolve most-specific-first (token → member → role → organisation default); the per-member budget cap resolves at the member and role levels only (budgets set on a token-attached guardrail are ignored).
 
 ## Single Sign-On & Directory Sync
 
 For enterprise teams, Eden AI supports:
 
 - **SSO**: enforce login through your identity provider (Okta, Azure AD, and others via WorkOS). Optionally require SSO for all members and route users by email domain.
 - **SCIM directory sync**: automatically provision and de-provision members from your IdP, and map IdP groups to Eden AI roles so role assignment stays in sync with your directory.
 
 Contact the Eden AI team to set up SSO and SCIM for your organisation.