Limits & tiers
Your pricing tier caps usage, and the caps come in two shapes — stock and flow. Knowing which is which tells you what to do when you hit one. The figures themselves live on the pricing page, which is the source of truth; this page explains the model so the numbers there mean something.
Stock limits and flow limits
A stock limit caps how many things exist right now. A flow limit caps how many things you do per calendar month. The four primitives split cleanly:
| Primitive | Limit kind | What it counts |
|---|---|---|
| Deadline | stock | open and overdue deadlines held at once |
| Watch | stock | active watches held at once |
| Schedule | flow | schedule.create calls this month |
| Approval | flow | approval.request calls this month |
The distinction is also a set of levers. A stock is something you can free up
without losing history: complete, cancel, or delete a deadline; pause or
delete a watch. Paused watches and completed/cancelled deadlines don't count —
they are how you stay under cap while keeping your data. (A watch on an erroring
source still counts as active and billable; pausing or deleting it is the
lever, per Watches.)
Poll-interval floors
Each tier sets a minimum watch poll interval. If you request a
Watch faster than your tier's floor, the interval is
clamped up to the floor — never rejected, never honoured below it. Higher
tiers have tighter floors (they can poll more often). The exact floors are on the
pricing page.
What happens at the limit
Stock caps are enforced at create time. Calling deadline.remember or
watch.create while already at cap returns a 409 Conflict with
{"error": "tier_limit_exceeded", ...} naming the limit and your current/max.
Recover by freeing a slot (complete/cancel/delete) or upgrading. If you
downgrade while over cap, nothing is auto-deleted — your existing commitments
keep firing; only new creates are rejected until you're back under.
Flow caps have a soft grace on paid tiers. Below 100% you're fine; between
100% and 110% requests still succeed but carry an
X-AIGears-Limit-Warning header (and a Dashboard notice); above 110% you get a
429 Too Many Requests. The grace exists because agents don't batch neatly
across a month boundary. The free tier has no grace — every cap is hard.
Whatever the surface, the Dashboard shows your current usage against each cap, so you can see a limit approaching before it bites.
Note what is not metered: webhook deliveries
and read calls (list / get / query / status / history). You're charged
for the state you hold and the writes you make, not for reading your own data or
receiving your own callbacks.
Audit retention by tier
How long your audit log is kept is also tier-bound — higher tiers retain a longer window. See the pricing page for the retention window at each tier.