Skip to content
LimitryLimitryLimitry Docs

Pools, balances and budgets

Pools, balances and budgets aren’t separate features. Each one is an ordinary limit, used in a particular way. Pools and balances use one example: customers buy credits that their whole team spends, at 25 credits a report.

Pools: an allowance a team shares

Section titled “Pools: an allowance a team shares”

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

{
  "subject": { "kind": "user", "id": "usr_123" },
  "shared": [{ "kind": "team", "id": "team_42" }],
  "action": "report",
  "cost": 25
}

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. That holds when a busy workspace’s counts are spread over several of Limitry’s servers too: a check whose subjects live on different servers is still all or nothing, and takes roughly 40 to 60 milliseconds more, as it saves on each server in turn. You can name up to 4 shared subjects, such as a team, its organization and a project.

Balances: prepaid credits

Section titled “Balances: prepaid credits”

Set the window to total. The amount is the starting balance, and it never resets. When a team buys 5,000 credits, add them to its balance:

import { createClient } from "@limitry/sdk";


const limitry = createClient();


await limitry.limits.credits.create("lmt_3f0c…", {
  subject: { kind: "team", id: "team_42" },
  amount: 5000,
  note: "October credits",
});

In the app, open the balance on the Limits page and choose Credits. Limitry keeps every credit added or taken back (limitry limits credits list <limit-id>).

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.credit).

To take credits back, after a refund or a chargeback, send a negative amount with a note that says why:

import { createClient } from "@limitry/sdk";


const limitry = createClient();


await limitry.limits.credits.create("lmt_3f0c…", {
  subject: { kind: "team", id: "team_42" },
  amount: -5000,
  note: "Refund of order 1042",
});

If the customer already spent those credits, the balance goes below zero. Checks are then refused until more credits bring it back above zero. In the app, choose Take back in the Credits dialog.

Budgets: a spending cap for an agent

Section titled “Budgets: a spending cap for an agent”

A budget is a limit counted in money. For example, $5 a day for every AI agent in your product, across everything it spends on models and paid tools:

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

Each check, with an action such as tool, passes the step’s price in cents as cost. When you don’t know the price up front, reserve what it will probably cost and commit what the call actually cost. Once the budget is used up, every check is refused until the window resets, or for a balance, until you add credits. With a total budget, the agent can ask a person for more credits (the limit.credit approval).

The Give AI agents a budget guide puts this together end to end.