# Budgets Look up the rules for budgets, spend limits, cost calculation and billing statements. For the ideas behind them, see [Budget and cost concepts](https://docs.atlas.ilionx.dev/concepts/budget-and-cost.md). For tasks, see [Set a space budget](https://docs.atlas.ilionx.dev/guides/admin/budget-and-cost-set-a-space-budget.md) and [Split a Team budget between members](https://docs.atlas.ilionx.dev/guides/admin/budget-and-cost-allocate-a-team-budget.md). All amounts are in euros (EUR). ## Budget hierarchy Budgets are set on spaces and cascade down the space tree. | Rule | Detail | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The root space has no budget | The root space has no budget field. Setting one, even `0`, is refused. The **Organization** tab shows the total handed out to its direct children | | Effective ceiling | The lowest of the space's own budget and every budget above it. If none is set anywhere in the chain, there is no limit | | No unlimited space under a budgeted parent | A child of a space with a budget must have a budget too | | Children add up | For each space with a budget, the budgets of its children together cannot exceed it | | Tighten only | A budget cannot exceed the ceiling cascaded from the spaces above | | Subtree floor | A space's budget cannot be lower than the sum of the budgets of all spaces below it | | Team with Fixed allocations | A Team's budget cannot be lower than the sum of its fixed member amounts | | Values | On any space below the root, a budget of `0` is valid and freezes spending. Negative values are rejected. An empty budget is not `0`. It means no limit, and applies only where no space above has a budget. Daily and monthly spending limits differ: they must be above zero or empty | | Slack | A space's own budget minus the sum of its children's budgets. Informational | | Moving a space | Only an Admin can move a space. The moved space and all spaces below it lose their budgets. A Team's member allocation returns to Pool | | Deleting a space | Its member allocations are removed with it | ### What each space type allows | Space type | Budget settings | | ------------------- | --------------------------------------------------------------------------- | | Organisation (root) | None | | Division or Unit | A monthly budget | | Team | A monthly budget, daily and monthly spending limits, and member allocations | ### Member allocation in a Team | Mode | A member's limit | Constraint | | -------------- | ------------------------------------------ | ---------------------------------------------- | | Pool (default) | The whole Team budget, shared by everyone | No individual allocations | | Fixed | The euro amount set for the member | Amounts together cannot exceed the Team budget | | Proportion | The member's percentage of the Team budget | Percentages together must equal 100 | A member with no allocation under Fixed or Proportion has a limit of €0 and is blocked. | Event | Result | | -------------------------- | ----------------------------------------------------------------- | | Proportion: member removed | The remaining shares are scaled up so they still total 100 | | Proportion: member added | The new member starts at 0% and is blocked until you redistribute | | Fixed: member removed | Others keep their amounts. The freed amount becomes unallocated. | | Fixed: member added | The new member starts at €0 and is blocked until you allocate | The page warns you when members are unallocated. ## Budget status The web app reports a member's position in a space with these fields. | Field | Meaning | | --------------- | ------------------------------------------------------------------------- | | Effective limit | The limit that applies to the member. Empty means unlimited | | Current spend | Spend in the current month | | Remaining | Effective limit minus spend, never below 0 | | Near limit | Spend is 80% or more of a non-zero limit | | At limit | Spend equals the limit | | Over limit | Spend is above the limit | | Limiting space | Shown when a space above yours, not your own space, is the tightest limit | - The period is the organisation's current calendar month in its [business time zone](https://docs.atlas.ilionx.dev/reference/budgets.md#business-time-zone). - Spend counts personal-key requests for every outcome (success, cancelled and error) that has a cost. Project traffic is excluded. - A space above you counts the spend of everything below it. - Members see only their own position. ### Utilisation bar Managers see a "Budget utilisation" bar per member. | Display | Condition | | --------------- | ------------------ | | Green | Below 80% | | Amber | 80% or more | | Red | 100% or more | | "—" | Unlimited | | "No allocation" | Blocked (limit €0) | For a personal API key, the key's details show your budget for the key's space. The figure is per person and space, not per key. A key is in one of these states: normal, near limit (amber), over limit (red), blocked (no allocation), unlimited or unbound (no space, no bar). ## What happens when a limit is reached ATLAS checks budgets before it sends a request to a provider. A request is refused with `429 budget_exceeded` (`402` with `billing_error` on Anthropic addresses). See [Errors](https://docs.atlas.ilionx.dev/reference/errors.md). ### Keys that act under a space Four checks run in order. The first used-up check refuses the request. | Order | Check | Refuses when | | ----- | ---------------------- | ------------------------------------------------------------------------------------------------------ | | 1 | Spaces above | A budgeted space above yours has used its monthly budget, counting everything below it | | 2 | Your member share | Skipped if the space has no budget. Refuses when your share is €0 or your month's spend has reached it | | 3 | Daily spending limit | Today's spend in the space has reached the daily limit | | 4 | Monthly spending limit | This month's spend in the space has reached the monthly limit | A request is refused once spend reaches a limit, not only when it goes over. The business time zone defines day and month. ### Keys that act under a project ATLAS checks project keys, and personal keys acting under a project, against the project's funding only. They never count against space budgets, and project spend is not counted in any space. | Funding mode | Refuses when | | ------------ | ----------------------------------------------------------------------------------------------- | | Funded | Nothing is allocated (add funds), or lifetime spend has reached the total allocated | | Tracked | A monthly limit is set and this month's spend has reached it. With no limit it is never refused | If ATLAS cannot read a project's budget position, it refuses the request with the usual budget error. The message says the position could not be determined and that this is an internal failure, not an exhausted budget. ### Good to know - Checks happen before the call. A running stream can overrun the limit, and ATLAS refuses the next request. - Every outcome that has a cost counts. For how failed and cancelled requests are costed, see [Pricing and cost](https://docs.atlas.ilionx.dev/reference/budgets.md#pricing-and-cost). - A model with no price set has no cost, so its usage is not counted towards any budget. ## Pricing and cost ATLAS gives every request that reaches a provider a cost when it records the request. | Step | Rule | | ----------------- | ------------------------------------------------------------------------------------------------------ | | 1. Provider cost | Model prices times tokens used. If a needed price or count is missing, the cost is empty | | 2. Currency | Converted to EUR at the rate in force (see [Currency](https://docs.atlas.ilionx.dev/reference/budgets.md#currency)) | | 3. Margin and fee | Your contract can add a percentage margin and a flat fee per request. Both are zero without a contract | | 4. Billed cost | Provider cost plus margin | How tokens are priced: - Uncached input is input minus cache-read and cache-write tokens. - An unset cache price falls back to the input price. An explicit `0` is free. - Reasoning tokens are part of output and are billed at the output rate. - Audio models can have a separate audio price. - Some models are priced per second, per character or per request instead of per token. The available units are: | Capability | Units | | ------------------------ | ------------------------- | | Chat, embeddings, rerank | Token, request | | Transcription | Token, second, request | | Speech | Token, character, request | - Requests that fail or are cancelled after reaching a provider are costed on input tokens. The count is estimated if the provider reported no usage, and as reported if it did. - Requests the provider rejected outright with no usage have no cost. Requests ATLAS refused before reaching a provider have no cost. - Batch, flex and priority tiers are not supported. ### Not set versus zero | State | Meaning | Shown as | | ------- | --------------------------------------------------- | ---------------------------------------- | | Not set | No price. Not costed and not counted in budgets | "Not set", with a warning on model lists | | `0` | Genuinely free. The flat fee, if any, still applies | A real €0.00 | ### Cache and reasoning reporting - Input is reported as uncached, cache-read and cache-write. Cache writes cost more than ordinary input and cache reads cost much less. - Reasoning is part of output and is reported separately. - Where a provider gave no breakdown, the page shows how many requests lacked one. It never shows `0` for missing data. - Organisations see billed cost and a single platform fee figure. Provider-side costs are not shown. ## Currency | Rule | Detail | | ---------------- | ---------------------------------------------------------------------------------------------------- | | Billing currency | Always EUR: costs, margins, billed cost, usage statistics, budgets and contract fees | | Model currency | A model's prices can be in EUR, USD or GBP. Costs are converted to euros using daily reference rates | | Rate unavailable | The request still succeeds, but its cost shows as unavailable and is not counted against budgets | ## Business time zone Each organisation has a business time zone, an IANA name such as `Europe/Amsterdam` (the default). It has these effects: | Effect | | ------------------------------------------------------------------------------------------------------------------------------------------ | | Budget periods, usage buckets, forecasts, project monthly spend and member usage start at midnight in this zone, including daylight saving | | Budget enforcement uses the same zone | Admins and Owners change it on the **General** tab of the organisation details. For the steps, see [Set the business time zone and download statements](https://docs.atlas.ilionx.dev/guides/admin/budget-and-cost-business-time-zone-and-statements.md). ## Billing statements | Statement | Subject | When | Content | | --------------------- | ----------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Monthly invoice | Organisation | Live preview while the month is open, frozen as a PDF at month close | AI usage through ATLAS, contract fees and a total | | Your AI subscriptions | Organisation | At month close, only if you used your own providers | A cost estimate for your own providers. "For information only. This is not an invoice." | | Contract | Contract revision | Once, when a revision takes effect | The contract as a PDF. Status Current, Superseded or Upcoming | | Internal allocation | Organisation | At month close, only with usage | What each Unit used, for charging back internally | | Unit cost report | Unit | At month close, only for Units with usage | A PDF for the Unit's managers | ### Monthly invoice | Rule | Detail | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | First period | The later of the organisation's creation month (a partial month counts) and the month its first contract revision takes effect | | AI usage lines | One line per model and AI service, sorted by amount. Deleted or renamed models and services keep the names they had when used and carry a red asterisk and footnote | | Own providers | Usage of your own providers is not on the invoice | | Contract fees | Platform fee, seats and licence. Total is AI usage plus contract fees | | Licence and seats | Taken from the contract revision active at the start of the month. Seats are billed every month | | Seats billed | The larger of the seat limit and the month's peak number of members, times the price per seat | | Licence rhythm | Counts from the first billed month of an unbroken run with the same billing period. A change of period restarts it. A one-off fee is billed once | | PDF titles | Organisation "Invoice ", project "Project cost report", Unit "Unit cost report" | ### Internal allocation - Shows what each Unit used (the Unit and its Teams, without projects), plus "Not allocated" and "Projects" lines. - It is informational and has no licence or seat fees. - Usage in a Division, in the root space, or with no space or project is "Not allocated". - Units, Projects and Not allocated together equal the cost shown in Explore. - Closed months stay frozen, including for spaces deleted later. ### Who can see statements | Where | Who | | ----------------------------------- | ----------------------------------------------------------- | | Organisation Statistics > Billing | Admins, Owners and Account Managers | | A Unit space's **Cost reports** tab | Managers of that Unit | | A project's statements | Admins, Owners, Account Managers and the project's managers | ## In the web app | Surface | What you see | | -------------------- | ----------------------------------------------------------------------------------------------- | | Space **Budget** tab | The layout depends on the space type. See [Budget tab by space type](https://docs.atlas.ilionx.dev/reference/budgets.md#budget-tab-by-space-type) | | Spaces tree | "€500 / mo" or "No budget" per space, with "Set budget" or "Set allocation" (not on the root) | | Members tab | Managers see a "Budget utilisation" column | | Personal API keys | Your budget in the key's detail panel | | Model lists | Price columns with a native or EUR toggle | | Billing | Statements, contract, internal allocation and deleted projects | ### Budget tab by space type | Space type | Shown | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Organisation root | "Organisation Budget": the total budgeted and a table of direct children. Admins edit children inline | | Division or Unit | Own monthly budget, a status bar and a "Child Space Allocation" table with children sum, slack and own budget. The space's manager edits the child cells | | Team | Own monthly budget, "Spending Limits" (daily and monthly) and "Member Allocations" (Pool, Fixed or Proportion, per-member values and a warning for unallocated members) | ### Who edits what | Space type | Own budget | Children's budgets | Member allocations | Spending limits | | ----------------- | ----------------------- | ------------------- | ------------------ | ------------------ | | Organisation root | n/a | Admin | n/a | n/a | | Division or Unit | Parent manager or Admin | The space's manager | n/a | n/a | | Team | Parent manager or Admin | n/a | The Team's manager | The Team's manager | - Root and direct-child spaces use "Budget" wording. - Spaces two or more levels below the root use "Allocation" wording ("Monthly Allocation", "Set allocation", "No allocation"). - Where a parent's cap is tighter than the space's own value, the page shows "Enforced limit … capped by a parent space". ### Live feedback while editing | Message | When | | ----------------------------------------------- | ------------------------------------------------------ | | "Value exceeds the €X parent cap." | The value is above the effective ceiling | | "Capped at €X by a parent budget/allocation." | A parent ceiling is tighter than the space's own value | | "€X of €Y remaining" or "Exceeds €X available." | Headroom left in the parent after its other children | Saving is blocked while one of these errors applies. The messages are hidden for the root space or an unbudgeted parent. ### Model list prices Model lists show **Input / 1M** and **Output / 1M** prices. The suffix follows the billing unit (per minute, per 1K characters, per 1K requests). - **Native** shows the model's own currency. **EUR** shows the converted value with the tooltip "Converted from {currency} at the rate effective {date}". - A model with no rate in force shows the native price with a warning. - A model with no price shows "Price not set — usage of this model is not costed and does not count towards budgets." - Cache prices are optional: "Not set — billed at the input rate." - Filters: Status, Source (Platform or Organisation) and Pricing (Priced or Price not set). Unpriced rows sort last. ## Related - [Gateway reference](https://docs.atlas.ilionx.dev/reference/gateway.md) - [Errors](https://docs.atlas.ilionx.dev/reference/errors.md) - [Roles and permissions](https://docs.atlas.ilionx.dev/reference/roles-and-permissions.md) - [Glossary](https://docs.atlas.ilionx.dev/reference/glossary.md) - [Reference index](https://docs.atlas.ilionx.dev/reference.md)