Pools, balances and budgets

Pools, balances and budgets aren’t separate features. Each one is an ordinary limit, used in a particular way.

Pools: an allowance a team shares

Put the limit on the shared subject, for example 10,000 AI calls a month for each team. Then name the team on each user’s check:

{
  "subject": { "kind": "user", "id": "u_7" },
  "shared": [{ "kind": "team", "id": "t_42" }],
  "action": "ai-call"
}

The check must fit every limit on the user and every limit on the team. It charges all of them, or none. However many of the team’s users check at the same moment, the pool is never overspent. You can name up to 4 shared subjects, such as a team, its organization and a project.

Balances: prepaid credits

Set the window to total. The amount is the starting balance, and it never resets. When a customer buys credits, add them with a grant:

curl -X POST https://api.limitry.com/v1/limits/$LIMIT_ID/grants \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": { "kind": "team", "id": "t_42" }, "amount": 5000, "note": "October top-up" }'

In the app, open the balance under Settings → Limits and choose Credits. Limitry keeps every grant (GET /v1/limits/{id}/grants).

When a balance runs out, the check’s retryAfterSeconds is null, because waiting won’t help and only more credits will. Owners and admins can add credits. An agent can ask to, and a person approves the request (limit.grant).

Budgets: a spending cap for an agent

A budget is a limit counted in money. For example, $50 a day for every agent:

Field	Value
Subject	agent (every agent, or one)
Action	*
Unit	cents
Amount	5000
Window	day, or total for one-off

Each check passes the call’s price in cents as cost. When you don’t know the price up front, reserve an estimate and commit what the call actually cost. Once the budget is used up, every check says no until the window resets, or for a balance, until you add more.

The Limit AI spend guide puts this together end to end.