Limits on any trigger

Tick a box instead of writing counters and conditions: the first time each day, every 3rd time, twice within 2 seconds, a cooldown, only while you are at the Mac, only on one Mac, only in a State.

Every trigger has a Limits section at the bottom of its settings. A limit changes how often or when the trigger may run the macro, whatever kind of trigger it is: a hotkey, a clipboard copy, a file, a webhook, the screen unlocking. You tick a box where Keyboard Maestro would have you keep a counter in a variable and test it in a condition.

You want	Set
The first unlock of the day	At most 1 per day
Every third time I open Twitter	Every 3rd time
Copy twice within two seconds	Twice within 2 s
This folder trigger, but at most once a minute	Cooldown 1 min
A break reminder, but only if I am here	Only when: At the Mac
A loud thing, only when nobody is home	Only when: Away from the Mac
One in ten times	Chance 10%
Only on the Mac Studio	On: Mac Studio
Only during Deep work	In State: Deep work

The trigger's sentence says what you set: The screen unlocks, the first time each day, Press ⌘C, twice within 2 s, A file changes in ~/Downloads, at most once a minute.

The fields #

Cooldown: after a run starts, the trigger is quiet for this long. It starts when the run starts, not when it ends.
At most (n) per (period): hour, day (local midnight), week (your calendar's first weekday), session (until the engine restarts or you log out) or ever. "The first time each day" is one per day. ever has a Reset button in the inspector.
Every (n)th time: runs on the 3rd, 6th, 9th occurrence. Skip the first counts from later: with every 2nd and skip 1, the 3rd and 5th run.
Twice within (seconds) (burst): runs on the occurrence that makes count within the window. After it runs the window clears, so three fast presses with a count of 2 run once, not twice. The first press of a pair does nothing and shows as burstShort in Not Fired. It works for any trigger kind: a clipboard copy twice, a webhook twice, a file twice.
Chance: runs this often, at random. A lost toss still counts toward every and at most, so "every 3rd time" stays every 3rd; it does not start a cooldown.
Only when: At the Mac means the screen is unlocked, no screen saver is running, and there was keyboard or mouse input in the last minute, or the front app is playing video or audio. Away from the Mac is the opposite.
On: the Macs the trigger is for. A trigger limited to another Mac shows Runs on Mac Studio and does nothing here. The library syncs between your Macs, so without this a trigger fires on all of them.
In State: runs only while one of these States is on.

Order #

The engine checks, in this order: the trigger matches, the macro's Only if passes, then the limits: Mac and State, attended, burst, every, at most, cooldown, and chance last. Because Only if comes first, a count is never spent on an event the macro would not have run anyway: "the first unlock today, only if on Wi-Fi Office" counts the first unlock on the office Wi-Fi.

What the macro sees #

Three tokens read what the limits counted for this run:

{{ trigger.count }}: this period's count, this run included (today's, when you set no at most).
{{ trigger.burst }}: the occurrence number inside the burst.
{{ trigger.occurrence }}: how many times this trigger has run, ever.

"Break number {{ trigger.count }} today" works with one tick on the trigger.

When a limit holds a trigger back #

Nothing runs and Activity ▸ Limits (also in Not Fired) says why, with how far along it is:

Reason	Meaning
cooldown	Still cooling down (`40 s left`).
limitReached	Already ran as often as at most allows in this period (`1 of 1 today`).
notNth	Not the nth time yet (`2 of 3`).
burstShort	Waiting for the rest of the burst (`1 of 2 within 2 s`).
chance	The coin toss said not this time.
unattended	The trigger is for while you are at the Mac, and nobody was.
attended	The trigger is for while you are away, and someone was at the Mac.
otherMac	The trigger is for another Mac.
notInState	The State it needs was off.

A run that a limit let through shows what let it through on its cause card: 2nd of 2 within 1.3 s, first today.

Good to know #

A run by hand, a dry run, a test, or a call from another macro ignores limits. The trace says limits skipped. Limits belong to the trigger.
Copying or importing a macro starts its counts at zero.
A hotkey with a burst takes every press of that key, including the first, so the app never sees it. For "copy twice" use a Clipboard change trigger with Twice within 2 s, not ⌘C as a hotkey.
The older knobs stay where they are. The cooldown and hold of A condition becomes true and A value changes belong to the condition they watch; a webhook's requests per minute and a folder's storm guard act before the event reaches a trigger. Limits are the user's intent: a cooldown here is silent and expected. The runaway breaker (a macro paused because it ran away) is a warning, a different thing.
Not here: "within N seconds of another trigger" (A, then B). A macro's triggers have no order between them. Use a burst for the same trigger twice.