Skip to content
LimitryLimitryLimitry Docs

When limits refill

A limit’s allowance refills at the end of each period. Three settings decide when:

Setting Decides Example
window The unit: minute, hour, day, week, month or year month
every How many units a period lasts (default 1) every: 3 with month is a quarter
start Where each period begins calendar, anchor or first_use

How often your customers pay doesn’t matter here. An annual plan can still refill its allowance every month.

The examples on this page give each team credits that its members spend on reports, at 25 credits a report. Unlike a prepaid balance, which never refills (see Pools, balances and budgets), these credits come back each period.

On the calendar

Section titled “On the calendar”

start: "calendar" is the default. Periods begin on UTC boundaries, the same for every subject:

  • day at midnight, week on Monday, month on the 1st, year on 1 January.
  • every: 3 with month refills on 1 January, April, July and October.
import { createClient } from "@limitry/sdk";


const limitry = createClient();


await limitry.limits.create({
  name: "Quarterly credits",
  subjectKind: "team",
  action: "report",
  amount: 15000,
  unit: "credits",
  window: "month",
  every: 3,
});

On each subject’s billing date

Section titled “On each subject’s billing date”

start: "anchor" refills each subject on its own date, its anchor. A team that subscribed on 17 March refills on the 17th of every month. Set a subject’s anchor when its subscription starts, usually from your billing webhook:

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


const limitry = createClient();


await limitry.limits.create({
  name: "Monthly credits",
  subjectKind: "team",
  action: "report",
  amount: 5000,
  unit: "credits",
  window: "month",
  start: "anchor",
});


// When the team's subscription starts (Stripe's start_date is in seconds)
await limitry.subjects.update("team", "team_42", {
  anchor: new Date(1773757800 * 1000).toISOString(),
});
  • No anchor yet: the subject’s first counted check becomes its anchor, so anchor limits work before you set one.
  • Annual plans: an annual subscription that started on 17 March still refills a monthly allowance on the 17th of every month. Set the anchor once, when the subscription starts.
  • Month ends: an anchor on the 31st refills on the last day of shorter months, then on the 31st again. An anchor on 29 February refills on 28 February in other years.
  • A new anchor starts a new period from that date. What was used in the old period no longer counts.

limitry subjects get team team_42 (or limitry.subjects.get("team", "team_42") in the SDKs) shows a subject’s anchor.

From first use

Section titled “From first use”

start: "first_use" starts a period at a subject’s first check and refills it a period later. Nothing runs while the subject is idle. This is how AI chat products allow “45 messages per 5 hours, starting from your first message”:

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


const limitry = createClient();


await limitry.limits.create({
  name: "Messages per 5 hours",
  subjectKind: "user",
  action: "chat",
  amount: 45,
  window: "hour",
  every: 5,
  start: "first_use",
});

Before a subject’s first check, its resetsAt is null. The check that starts the period already answers when it ends.

Reset now

Section titled “Reset now”

Refill a subject’s allowance at once, for goodwill, a promotion or support. Name one limit, or send {} to reset every limit on the subject:

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


const limitry = createClient();


await limitry.subjects.reset(
  "team",
  "team_42",
  { limitId: "lim_3f0c…" },
  { idempotencyKey: "ticket-8812" },
);
  • The schedule doesn’t move: the next refill is still the usual one.
  • A balance (total) goes back to its amount. Credits granted before the reset no longer count.
  • A concurrent limit is skipped. Its slots belong to work that’s still running.
  • With an idempotency key, a repeated request resets once.

In the app, owners and admins can click Reset next to a subject on the Usage page.

Stacking limits

Section titled “Stacking limits”

Every limit that matches a check applies, and each refills on its own schedule. Monthly credits with a daily cap against abuse are two limits:

Limit amount window start
Monthly credits 5000 month anchor
Daily cap 500 day calendar

Limitry refuses a team after 500 credits in a day (20 reports), even with credits left for the month. See Offer a free plan with a daily cap.

What answers show

Section titled “What answers show”

A check’s remaining[].resetsAt and usage.standing say when that subject’s own period ends. For anchor and first_use limits, that’s different for every subject. The Usage page’s Right now table shows each subject’s use and refusals in its own current period, resets included.