# Entitlements, limits, and resets

> What a plan allows: entitlement and limit fields, hard, soft, and observe modes, resets and calendar schedules, rate limits, and org scope.

# Entitlements and limits

An **entitlement** is something a plan allows: a feature, an API, AI tokens, seats. With no limit it's a feature flag
(the plan has it or it doesn't). With a **limit** it's metered in a [credit](./credits), and each customer gets a
meter for it.

```stof
policy: {
    credits: {
        request: { label: 'Request' }
        ai_token: { label: 'AI token', price: { amount: 0.00002 } }
    }
    plans: {
        pro: {
            default: true
            entitlements: {
                // A feature flag
                sso: {}
                api: {
                    limit: {
                        credit: 'request', value: 100_000
                        resets: true, reset_sch: 'monthly:1'
                    }
                }
                chat: {
                    description: 'AI chat'
                    estimate_basis: 'input'
                    estimate_segment: 'model'
                    limit: {
                        credit: 'ai_token', mode: 'soft', value: 2_000_000
                        resets: true
                    }
                }
            }
        }
    }
}
```

## Entitlement fields

| Field | Type | Default | Notes |
|---|---|---|---|
| `limit` | Limit | null | No limit: a feature flag. |
| `description` | str | `''` | |
| `scope` | str | null | Meter on the nearest customer of this type through refs (Ex. `'org'`). See [Scope](#scope). |
| `enabled` | bool or fn | (absent) | Whether it's on for a call. See [Feature rules](./feature-rules). |
| `track` | bool | false | Send `feature-checked` each time it's checked. See [Feature rules](./feature-rules). |
| `estimate_basis` | str | null | Event data field a call's size depends on (Ex. `'input'`). See [Reservations](./reservations). |
| `estimate_segment` | str | null | Event data field that keeps separate estimates (Ex. `'model'`). |
| `hidden` | bool | false | Not used by the engine. A flag for your own UI. |

The same entitlement name can appear in several plans with different limits: `api` might be 1,000 a day on Free and
100,000 a month on Pro. Your code calls `allow(id, 'api', 1)` either way.

## Limit fields

| Field | Type | Default | Notes |
|---|---|---|---|
| `credit` | str | (required) | The credit this limit is counted in. |
| `value` | number or units | 0 | The limit, in the credit's units (`1000`, `'1GB'`, `2hr`). |
| `mode` | str | `'hard'` | `hard`, `soft`, or `observe` (below). |
| `resets` | bool | false | Start the meter over each period. Setting `reset_sch` turns it on. |
| `reset_inc` | duration | 30 days | Period length (`1s`, `1hr`, `1day`, `30days`). Used when `resets` and no `reset_sch`. |
| `reset_sch` | str | null | `'period'` (each billing period) or a calendar schedule, in UTC (below). Can't be used with `reset_inc`. |
| `increment` | number or units | 1 | The step for `increment` and `decrement`, and the standard size of a call. |
| `minimum` | number or units | null | The meter never goes below this. |
| `hard_trailing` | bool | false | Hard only: allow a call while the meter is under the limit, even if the call crosses it. |
| `grants_apply` | bool | true | Whether grants can cover usage past the limit. Set false on safety limits. |
| `governor_enabled` | bool | false | Add a token-bucket rate limit (below). |
| `governor_capacity` | number | null | Bucket size: the largest burst. Required with a governor. |
| `governor_refill_rate` | number | null | Tokens added per millisecond (0.001 is one a second). Required with a governor. |
| `ewma_alpha` | float | 0.2 | Smoothing for the usage rate trend (0 to 1). |

## Modes

| Mode | Past the limit | Event |
|---|---|---|
| `hard` | Denied. Nothing changes. | `meter-limit` |
| `soft` | Allowed. The part past the limit is **overage**: grants cover what they can, and the rest is billed. | `meter-overage`, with `overage_price` |
| `observe` | Allowed. Usage is only recorded. | `meter-changed` |

Use `observe` to track a feature before pricing it, or to try a new limit without blocking anyone. `remaining` is
null for observe limits.

With `hard_trailing: true`, a hard limit lets through the call that crosses it (the meter was under before the call)
and denies the calls after. It suits usage you only know after the fact. On a 100 limit at 90, a 50-unit call is
allowed (140), and the next call is denied.

## Resets

A limit with `resets: true`, or a `reset_sch`, starts a new period:

- **Rolling** with `reset_inc`: that long after the last period began. 30 days if you don't set one.
- **Each billing period** with `reset_sch: 'period'` (0.7.5 and later): when the customer's billing period starts
  again, so usage starts over as their bill does. The period is the customer's `period_start` and `period_end`.
  Limitr Cloud keeps them in step with each customer's invoices; without Cloud, set them from your subscription with
  `set_customer_period(id, start, end?)` (TypeScript: `setCustomerPeriod`). A customer with no dates follows the
  plan's `period` on the calendar (the 1st of the month for a monthly plan, January 1 for a yearly one). Topups and
  caps take `'period'` too.
- **Calendar** with `reset_sch`, in UTC, for every customer at once:

| Schedule | Resets |
|---|---|
| `monthly:1` | On the 1st of each month. Use a day from 1 to 28, or `monthly:last` for month ends. |
| `monthly:last` | On the last day of each month. |
| `weekly:mon` | Every Monday (`mon` to `sun`). |
| `nth_weekday:2:tue` | On the second Tuesday of each month. |
| `quarterly:1` | On day 1 of each quarter. |
| `semiannual:1-1` | Twice a year: January 1 and July 1 (`month-day` and six months later; engine 0.8). |
| `yearly:1-1` | On January 1 (`month-day`). |

Nothing runs on a timer. The engine notices a period ended the next time the meter is used or read, so there are no
jobs to keep alive. A call that starts a new period also sends `meter-reset`. `resets(id, entitlement)` returns when the
current period ends, in milliseconds.

A limit with no reset is a running total (storage, seats), and usage can go back down with a negative value or
`decrement`.

## Governors

A governor limits the rate of calls, below the limit, with a token bucket: `governor_capacity` tokens, refilled at
`governor_refill_rate` tokens per millisecond. Each call spends its value in tokens: `allow` when it's counted, or
`reserve` for the amount it holds (`settle` trues that up to the real usage, `release` gives it back). A call without
enough tokens is denied and sends `meter-governed`.

```stof
chat_rate: {
    limit: {
        credit: 'request', value: 1e9, grants_apply: false
        // Bursts of 5, then 1 a second
        governor_enabled: true, governor_capacity: 5, governor_refill_rate: 0.001
    }
}
```

A huge `value` makes the governor the only thing that matters. Governors work on hard limits. `allowance(id,
entitlement)` is what can run right now: the room left, capped by the tokens in the bucket. See
[Rate limits](../how-to/rate-limits).

## Scope

`scope: 'org'` meters the entitlement on the nearest customer of type `org` through the caller's refs, whichever user
calls. Seats are the usual case: any user's invite counts against the org's seats. A caller with no customer of that
type in its refs is denied. Scope works with any customer type (`'team'`, `'workspace'`).

## How a call is decided

`allow` and `check` go through these steps. Nothing changes until every step passes.

1. **The entitlement.** The customer's plan has it (or it was given, and not taken), and its `enabled` rule (if any)
   is on. A feature flag stops here: allowed.
2. **Period reset.** If the limit resets and the period ended, the meter starts from zero.
3. **Spend caps.** Every cap that applies has room: the customer's own, shared caps from its refs, and any cap passed
   with the call.
4. **Grants.** Usage past the limit is drawn from the customer's grants first.
5. **Governor.** There are enough tokens in the bucket.
6. **Limit.** Hard denies past the limit, soft allows and bills the overage, observe allows.
7. **Commit** (`allow` only). The meter, its recorded cost, grants, and caps move, and events are sent.

`check` makes the same decision without changing anything. Two `check`s can both pass when only one call fits, so use
[reserve and settle](./reservations) when calls run at the same time.

**Unknown customers and entitlements are denied.** Nothing throws, and nothing is allowed by mistake.

### Why a call was refused

Both return true or false by default. Pass `detail` (the last parameter) and they return the decision instead: whether
it was allowed, the `reason` when it wasn't, and where the customer stands (after the call for `allow`, as things are
for `check`): `used`, `limit`, `remaining`, `allowance`, `held`, `resets`, plus where access and the limit come from.
Hand it to the customer, or back to an agent as a tool result.

| `reason` | What refused the call |
|---|---|
| `no_customer` | No such customer (or Limitr Cloud couldn't load it). |
| `unconnected` | The SDK is connected to Limitr Cloud, the connection is down, and it denies while unconnected. |
| `expired` | The customer's access has ended. |
| `not_entitled` | Neither its plan, its gives, its rules, nor its refs have the entitlement. |
| `taken` | Taken from the customer, or by one of its rules. |
| `no_scope` | The entitlement is scoped to a customer type with none up the customer's refs. |
| `disabled` | The entitlement's `enabled` rule said no for this call. |
| `cap` | A spend cap has no room (the decision names it, `cap` and `cap_customer`). |
| `governor` | The governor hasn't refilled enough (`available` says how much it has). |
| `limit` | A hard limit, with no grants left to cover the rest. |
| `held` | The call fits on its own, but room held by reservations doesn't leave enough. |

<Tabs groupId="lang" queryString>
<TabItem value="typescript" label="TypeScript">

```ts
const d = await limitr.check('ada', 'api', 50, undefined, undefined, true);
if (!d.allowed) console.log(d.reason, d.remaining, d.resets);   // Ex. 'limit' 12 1796083200000
```

</TabItem>
<TabItem value="python" label="Python">

```python
d = limitr.check('ada', 'api', 50, detail=True)
if not d['allowed']:
    print(d['reason'], d['remaining'], d['resets'])   # Ex. limit 12 1796083200000
```

</TabItem>
</Tabs>

## Values

- **Units.** Values can carry units in a string (`'250MB'`, `'2.5GB'`) or in Stof (`250MB`).
- **Negative values** decrement. They're always allowed, and the meter won't go below `minimum`.
- **`increment` / `decrement`** move the meter by the limit's `increment`.
- **`force`** (on `allow`) records usage that already happened, past a hard limit or cap. `settle` uses it.

## Stacking

One action can be metered by several entitlements at once, each with its own credit, mode, and reset: a report counts
against a monthly report allowance and uses AI tokens billed past an included amount. Go in an order where a refusal
never leaves anything half counted:

1. **Gates:** `check` feature flags. Nothing changes.
2. **Measures** (known only afterwards, Ex. tokens): `reserve`. A hold is free to give back.
3. **Counts** (known now, Ex. one report): `allow`. If one is refused, `release` the holds and stop.
4. Run the action, then `settle` each hold with what it really used.

Rate limits hold either way: `reserve` spends a governor's tokens for what it holds, like `allow` does. See the
[stacking tutorial](../tutorial/stacking-entitlements).

## Overrides

An override replaces an entitlement's limit for one customer: a bigger allowance, a different mode, a trial. See
[Customers](./customers#overrides).

## Reads

Reads never meter anything, and they show the current period even before a pending reset happens.

| Call | Returns |
|---|---|
| `value(id, entitlement, percent = false)` | Usage this period (or the percent of the limit, up to 100). |
| `remaining(id, entitlement, percent = false)` | The limit minus usage, plus grants. Null for observe limits. |
| `limit(id, entitlement)` | The limit, plus grants that apply to it. `id` can be a plan. |
| `allowance(id, entitlement)` | What can run right now, counting the governor. |
| `cost(id, entitlement)` | The standard increment. |
| `resets(id, entitlement)` | When the meter resets next (ms), or null. |
| `rate(id, entitlement)` / `acceleration(id, entitlement)` | Usage per millisecond, and its change. |
| `projectedExhaustion(id, entitlement)` | When the limit runs out at the current rate (ms), or null. |
| `entitlement(id, entitlement)` | The entitlement as the customer has it. |
| `meterObject(id, entitlement)` / `limitObject(id, entitlement)` | The meter and limit records. |

The `grants` argument (default true) on `value`, `remaining`, `limit`, and `allowance` says whether to count grants.
