Budget pools
A budget pool is a monthly cap shared by a group of API keys. A pool is either a developer pool (people's keys and service keys for pipelines) or an agent pool (agents' credentials), never both. Every call a member key makes counts against the pool, on top of the workspace, model, key and agent caps. Whichever cap is reached first blocks the call.
Pools are available on the Pro and Enterprise plans. They live on Budgets → Pools.
How a pool applies to a call
A call is charged to the pool of the API key that made it. A person with several keys can have a key in each of several pools. Console calls use no API key, so they aren't charged to a pool.
The call is refused before it reaches the provider if:
| Check | Refusal |
|---|---|
| The pool's monthly limit would be exceeded | 402 pool_budget_exceeded |
| The caller's share of the pool would be exceeded | 402 pool_member_share_exceeded |
The check uses the call's projected cost, like other budgets. Members' own key budgets may add up to more than the pool. The refusal says which limit was hit and who owns it. For example:
Key "laptop" (Ada) has used its $25.00 share of budget pool "Platform" ($24.90 spent this period). Ask Priya to raise the share.
See Pool API and errors for the response bodies.
Rules that hold for every pool:
- A key is in at most one pool.
- A pool holds one kind of key, chosen at creation and fixed after.
- A pool's limit cannot be higher than the workspace's monthly budget.
- A pool does not replace the other caps. A key with its own daily cap still stops at that cap inside a pool.
Count a pool in dollars or in tokens
A pool is capped in one unit, chosen when you create it: US dollars (the default) or tokens. On Budgets → Pools → New pool, the Pool budget field has a USD | Tokens switch. Everything else works the same in either unit: shares (equal or set by the lead), burst, a per-key maximum, alerts and the refusal.
A token pool counts prompt and completion tokens. Image and audio calls carry no tokens, so a token pool doesn't count them; each key's own dollar limits still apply to them. You can't change a pool's unit later. Create a new pool instead.
Token pools differ from dollar pools in two small ways:
- The limit can't be more than the workspace's monthly token cap, if it has one. A dollar workspace budget doesn't limit a token pool.
- The spend forecast isn't available (it projects dollars).
Requests for a higher limit or a bigger share work the same way; the amounts are in tokens.
The refusal for a token pool speaks tokens, for example: Budget pool "Research" has reached its 50,000,000 tokens limit (49,999,990 tokens used this period). Its body has unit: "tokens" and limit_tokens, used_tokens, attempted_tokens instead of the dollar fields.
Create a pool
Only admins create pools.
Open the form
On Budgets → Pools, click New pool.
Basics: name, who is in it, limit
Under Who is in it, pick Developers or Agents. Set the pool budget in USD. It's a monthly cap unless you give the pool a span. For a developer pool, add people, keys, or both. A person brings their one free key, or is issued one if they have none (see Adding a person who has no key). A key can be a service key or a specific developer key. For an agent pool, add the agents' keys; there are no people. A key already in another pool is dimmed; hover over it to see which pool.
Pick a lead (optional)
The lead divides the pool between its keys and can file requests for changes. The lead must be an admin or an owner, or someone who owns one of the pool's keys. With no lead, only admins change shares.
Choose how the limit is shared
Leave Share the limit equally on for an equal split. Turn it off to type an amount per key. See Shares and burst.
Active period (optional)
Set a start day and an end day, and turn on the forecast if you want a warning before the pool runs out.
Alerts (optional)
Choose the percentages and who is told. When you pick a lead, their email is added to the alert list for you. See Pool alerts.
Click Create pool
The pool applies from the next call. If the button is disabled, the reason is shown at the bottom of the form.
Adding a person who has no key
A pool needs a key to charge, so adding a person to a developer pool gives them one (agent pools have no people):
- With one key that is in no pool yet, that key is used and nothing new is issued.
- With no key, a key is issued for them, owned by them and not yet usable. They are notified, in the bell and on the notifications page, and reveal it on API Keys. The secret is shown to them once. The admin who added them never sees it.
- With several free keys, the console warns you and narrows the key list to theirs. Add the key you mean instead.
- With keys all in other pools, a new key is issued, as if they had none. The console warns you first and names those pools, so you can move one of their keys instead.
A Session Insights CLI key can't call the gateway, so a person whose only key is a CLI key counts as having none.
Everyone in a new pool is notified once, in the bell and on the notifications page, with the name of the person who added them.
Only builders, admins, owners and members whose custom role includes key access can hold a key. Shares are per key, so a person with two keys in a pool has two shares.
A key stops counting as a member when it's revoked, its owner is deactivated, or its agent is retired. The remaining keys' shares go up.
Form reference
| Field | What it does |
|---|---|
| Pool budget | The most the pool can spend in a month. For a pool that applies over a whole span, the budget for the span. Stored and returned by the API as monthly_limit_usd. |
| Starts on / Ends on | The pool only applies from the start day through the end day. Both days are included, in your browser's time zone. Leave both empty for a pool with no end. |
| The limit applies | Each month resets the limit monthly while the pool is in force. Over the whole span is one limit for everything between the two dates and needs both. |
| Forecast | Projects when the pool runs out from the last seven days of spend, and sends an alert if that is before the period ends. The alert goes to the people the pool's alert settings tell. |
To create a pool for a team with its people already added, open the team on Members → Teams and use + Create budget pool. See Teams.
Who sees what
| Role | Can do |
|---|---|
| Admin or owner | See every pool. Create, edit, archive and delete pools. Add and remove members. Change shares. |
| Pool lead | See their pool and everyone's usage in it. Change shares and burst. File requests for a higher limit and for new members. |
| Key owner | See a pool that holds one of their keys, its share and its usage. Ask for a bigger share for a key they own. |
| Everyone else | Cannot see the pool. Requests for it return 404. |
Admins and owners always see the Pools tab. A viewer or builder sees it only when they own a key in, or lead, at least one scheduled or active pool, and then only their own pools. Anyone else gets the same "admin-only view" panel as the other Budgets tabs.
Forecast visibility
The forecast exists only when it is turned on for the pool. Without it, the forecast endpoint returns 409.
| Who | Sees |
|---|---|
| Admins and the lead | The pool and every member |
| A member | The pool and their own row only |
| Anyone else | Nothing. The request returns 404 |
Status
| Status | Meaning |
|---|---|
scheduled | The start day has not arrived. The pool does not limit anyone yet. |
active | In force. |
expired | The end day has passed. Members are released. |
archived | Closed by an admin. Members are released. The pool stays in the list with its final spend. |
Archive or delete
Archive releases the members and keeps the pool in the list. Delete removes the pool for good. On a pool that is still active, Delete releases its members first, in the same step.
Deleting a pool removes its alert history and the email alerts that only watched that pool. Usage records keep their pool stamp, so past spend and totals do not change, and the audit log records the deletion with the pool's lifetime spend.
Neither action can be undone.