Concepts
The terms used across the project and docs.
All of the vocabulary and concepts are listed most important to least. Reference pages link back here rather than re-explain.
Policy
The configuration document that defines a product's usage monetization, control, and analytics strategies in their entirety.
Fully managed in Limitr Cloud, or written with JSON, YAML, TOML, or Stof, following the spec.
Contains credit definitions (tokens, GPU seconds, abstract credits, or anything countable), overhead costs, your prices, plans, credit exchange rates, included limits, topups, entitlements — everything defined outside of customer state.
Credit
The definition of a descrete unit of value that can be delivered or used within your product.
This can be a vendor unit that your product consumes, a unit of value you deliver to your customers, or a single line item/purchase.
Credits define the measurement units kept within meters and the units returned within SDK calls: int, float, seconds, MiB, any Stof unit.
Because we have native types for things like seconds in the runtime, you can set limits in days for example, then meter in a mix of ms, s, hrs, and have all value, remaining, etc. SDK calls return numbers that always are in seconds.
Discrete Credit — Tied to a specific resource with real cost attached, either an overhead_cost or price, or both.
- AI input token that costs you $0.000004 per token to use
- GPU second that you charge your users for
- A megabyte of storage that you want to keep track of
- One SMS message that has a cost to send
- Currency definition & exchange rates (e.g. Euro, Kroner, USD, British Pound)
- Note: Limitr Cloud comes with currency exchange, you'll need a bit of Stof know-how if you want real-time exchange lookups with the open-source engine alone
Abstract Credit — A credit definition that only has meaning in your product(s), may or may not have costs attached.
- A flat monthly plan subscription cost
- Single seat in your platform
- User-facing credit that customers have a balance of, or purchase quantities of
- Single SKU that you charge for
The Credit is the only concept in Limitr that relates to money — any unit of value with a price, cost, or unit that matters to you or your customer (real or "fake") is a credit.
The Exchange Table defines transforms between credits (can be multi-step), so that you can cap, limit, measure, analyize, etc. usage in the credit/units of your choice, always.
The Rune
There's one abstract credit that is always defined, called the Rune or rune in each policy.
It's main purpose is to give us a common base unit that is detached from real currency, it enables global credit exchanges, and has other benefits as well.
When you set a price or overhead_cost or tiers on a credit, the defined value (float) is in runes, not USD.
By default, a single Rune is defined as $1 USD, so technically, the units can be used interchangeably, and you can think of prices as USD in the config.
I highly recommend you keep this setup, even if you use euros or something in your stack — I promise, things will work out better for you if you do. But if you must, you can change this definition and everything will still work fine.
If you're using Limitr Cloud, this complexity is abstracted away for the most part. When you set prices in USD, we exchange it to runes for the policy config, and then back to USD for the UI.
Exchange
An object within the policy that defines credit relationships and conversions. All values are expressed relative to the rune, where 1 rune = 1 USD by default.
The exchange table is what allows a pool of abstract credits to drain across multiple discrete entitlements, and what enables margin calculation across any combination of resources.
Any credit with a price or tiers defined (in runes) automatically has an exchange rate at that price. Yes, tiered pricing is taken into account during the exchange as well — flat, tiered, volume, or stairstep pricing.
- flat — a single price per unit, applied uniformly regardless of how much is consumed.
- tiered - like tax brackets, each band of consumption has its own per-unit price, and you pay each band's rate only for the units consumed within that band.
- volume - your total consumption determins a single per-unit rate, applied retroactively to all units consumed.
- stairstep - a flat fee per band, where your total consumption determines which band you're in and you pay that band's fixed price regardless of where within the band you land.
Grant Strategy
The rule that governs which grant is consumed first when multiple customer credit grants are eligible. Grants defined in the credit of consumption are always used first, regardless of strategy.
Only useful if you have multiple abstract, user-facing credits — not desireable, but sometimes necessary (migrations, acquisitions, merging customer objects, honoring old topup purchases, etc.).
Don't worry about this setting until you encounter a behavior that needs changing. The default "expires_first" strategy is most certainly what you'll want.
expires_first— (default) prefer to use the credit grant that expires firstcheapest_first— choose the lowest rune value per unit (convert to credits that are cheapest, uses more)valuable_first— choose the highest rune value per unit (convert to credits that are most expensive, uses less)
Plan
A named tier bundling entitlements for customers — free, starter, growth, enterprise, or whatever your product defines. Plans specify which credits customers on that tier can consume, at what limits, and which topups are available or included automatically.
Every customer is on exactly one plan at a time.
A plan can be for your paying users, like free, starter, etc. But it could also be internal-facing to control your own usage: workspace plan, agent plan, high-availability plan, etc.
Limitr does not restrict the types of "customers", so a user customer object with limits is just as valid as an agent customer object that owns usage state for one of your internal AI agents.
And remember, you can always stack entitlements — they work together (e.g. user gets 1000 tokens per hour, agent gets 500 per hour, both must allow(...) -> true for the vendor call to occur).
Entitlement
A specific resource a customer on a plan is allowed to use. Could map to a feature (e.g. ai-chat), a vendor line-item (e.g. sonnet-input-tokens), or anything you'd like to gate or control.
Entitlements live inside plans and are identified by name (chat_input, seats, pdf_export).
- Without a limit — acts as a boolean flag. Present means allowed; absent means denied.
- With a limit — metered. Consumption is tracked and enforced against the limit - optionally billed for overage if overage allowed.
Entitlements can be scoped to specific types of customers. Each customer has a type (user, org, agent, workspace, etc.), and if an entitlement has a scope, it can only be applied to that type of customer.
Customers reference each other, so Limitr will auto-resolve customer references to the required scope of an entitlement when used. For example, an org might have a limit on seats — users in that org don't, but the seats entitlement is scoped to org, so even when a user ID is passed into allow(userId, 'seats', 1), Limitr resolves the org customer instead (shared meters).
Limit
The constraint on an entitlement that allows/represents consumption. References the credit being metered by name (e.g. seats, sonnet-input-token), defines a limit value (units of the credit), and how enforcement behaves when the limit is reached.
| Mode | Behavior |
|---|---|
hard | Blocks at the limit (default post-op value comparison). No overage allowed (except when covered by a grant). Fires meter-limit events when hit. |
soft | Allows consumption past the limit. Fires meter-overage events for all overage that occurs. |
observe | No enforcement. Meters indefinitely. Useful for visibility & analytics without blocking (e.g. logins, runs). |
Limits can reset on a schedule — either a fixed duration (reset_inc: 30days) or a calendar boundary (reset_sch: 'monthly:1'). They can also carry a governor — a token bucket rate ceiling below the hard limit that shapes consumption proactively rather than suddenly cutting customers off. Limits can be overridden per-customer without changing the plan.
Customer
Any entity that is controlled by or consumes entitlements — a user, an organization, a workspace, an agent. Customers are identified by a primary ID, can carry alternative IDs (e.g. a Stripe customer ID), and can reference other customers (e.g. a user referencing its org for a shared limit or meter).
Each customer carries their own caps, meters, overrides, and grants.
Meter
The per-customer, per-entitlement consumption counter. Updated automatically on every allow(), increment(), or decrement() call. Stores the credit ID, current value, and a short history of recent consumption events.
From the history, Limitr derives a real-time consumption rate and projected exhaustion timestamp — how long until the customer runs out at their current pace. When a governor is configured, the meter also tracks the token bucket state used for rate enforcement.
Meters reset when their entitlement limit's reset schedule fires (can be overridden per customer).
Grant
A credit balance on a specific customer, created when a topup is applied (or included, potentially on a schedule). When a soft-limit entitlement goes into overage, Limitr draws from the customer's eligible grants before any overage is emitted or recorded.
Grants track their starting_value, current value, reset behavior, expiry, and which topup created them (if at all).
Spend Cap
A spend cap is a high-level tool tied to a customer that contains it's own state and sits outside of the policy definition.
It's purpose is to either observe or control spend (in any credit or exchange units), either temporarily, permamently, or on a schedule.
Even if a limit is soft and allows overage, a spend cap can block an allow(...) or check(...) to protect or enforce spend tied to this customer.
Can be applied in many situations, including but not limited to:
- Self-serve USD or credit spend caps (user can set these for themselves)
- Internal overhead spend caps (works on
overhead_cost, too) — e.g. cap an AI agent to $15 in AI per month across all vendors - Measure spend & margin over a single pipeline run — involving many vendors, prices, etc.
Spend caps work, even with user-facing credits, grants, included usage limits, etc. All of these edge cases are handled, making spend caps one of the more powerful tools in the project.
Topup
A credit package that can be applied to a customer — purchased explicitly or included automatically in a plan. When applied, a topup creates a grant on the customer.
Topups can carry a price, reset on a duration or calendar schedule, support rollover, and expire after a configurable period.
Notification
A policy-defined rule that fires when a specific event condition is met. Written in Stof. Defines a matches(type, event) function to filter events, and a fire function to handle them.
Notifications happen in real-time, and can route-automatically to Slack, email, etc. Locally, they fire in-process, allowing you to attach or inject your own handlers where desired.
If you're using Limitr Cloud, real-time notifications are configured in the UI, routed to your team of choice the millisecond thresholds are crossed/matched, and can be used throughout your organization for usage-tied insights and responsibilities.
Capability
A named, callable unit of policy logic with defined input/output parameters. Used to expose policy-aware functions as dynamic tool definitions — for example, as Claude MCP tool definitions in an agent pipeline.
Capabilities are an advanced concept, involving some Stof know-how. However, a powerful mechanism for policy-aware contexts and custom tooling.
The Limitr team is excited to help any Limitr Cloud customers with premium support create capabilities and tooling. Reach out on Slack whenever you need.
As such, they may be shown in cookbooks or guides, but not explicitly covered outside of this concepts page. Here's a brief example:
import { Limitr } from "@formata/limitr";
/** Setup your policy per usual. */
const policy = await Limitr.new();
/** TypeScript function that I want to make into a policy-aware capability. */
async function doTheThing(url: string): Promise<number> { return url.length; }
policy.doc.lib('Host', 'do_the_thing', doTheThing); // expose to the Stof wasm sandbox
/** Add Stof capability/tooling inside the policy to do_the_thing - can add usage, enforcement, etc. */
await policy.setCapabilities(`
do_it: {
parameters: [{ name: 'url', description: 'A URL string.' }]
#[run] fn execute() {
const res = await Host.do_the_thing(self.input.url ?? 'dne');
self.set_result(res ?? 0);
}
}`);
/** Now we have "do_it" as a policy capability, accessible to anything that has the policy! */
console.log(await policy.runCapability('do_it', { url: 'https://doin_it.com' })); // 19
/** Capabilities generate tools automatically and can be used out of the box with Claude. */
console.log(await policy.claudeTools());
/** Pass tool use blocks right into the policy to use with capabilities. */
const toolUse = {
type: 'tool_use',
id: 'toolu_21345',
name: 'do_it',
input: { 'url': 'http://z.ai' }
};
const result = await policy.claudeToolUse(toolUse);
console.log(result);