Caps and windows

A cap counts spend over a window, and the window is a clock. When the window closes, the count starts again from zero; a lifetime cap never closes.

The five windows

Every boundary is UTC, for every organization. A monthly cap in Denver still resets at 00:00 UTC on the 1st, which is the evening of the last day of the month there; the platform prints each boundary in UTC and in your own clock so the two are never confused. month is the default window.

What "week" means

A week is an ISO week: it opens on Monday at 00:00 UTC and closes at the next Monday's 00:00 UTC. Its period key is written YYYY-Www, and the year in it is the ISO week-numbering year, which is not always the calendar year for the first and last few days of a year:

• Monday 29 December 2025 opens week 2026-W01;
• Friday 1 January 2027 is still in week 2026-W53, which runs until Monday 4 January 2027.

So a weekly cap never resets at New Year unless New Year is a Monday. It resets on Mondays, and only on Mondays. A weekly cap's refusal says so in its own word: "Weekly budget reached. Traffic resumes at reset, or raise the cap."

How a window resets

Nothing clears a counter. Each window's count is kept under its period key, and the first request of a new period reads a key that has no count yet, which is zero. That is why a reset needs no job to run: the date moving on is the reset.

The same key is why alert thresholds re-arm on their own: a threshold fires once per cap, per period, per percentage, and a new period is a new key (Alert thresholds).

A lifetime cap names one key forever, so it counts every dollar since the cap was created and never reopens. Its refusal says "This budget does not reset; raise the cap to continue."

Several caps on one scope

A scope can carry several caps on different windows: a daily cap and a lifetime cap on one key, or a monthly and a yearly cap on the organization. Each keeps its own count on its own clock. At admission every armed cap that covers the request is checked, and the tightest decides: if the daily cap is reached, the request is refused with the daily sentence even though the lifetime cap has room.

Two caps on two clocks have no total, so nothing adds them up.

The run envelope

A run's budget is a sixth window, run, and it is not a clock at all: it opens with the first request that names the run and never reopens once reached. It nests inside the caps above it and can only tighten them. Breaker describes it.