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 |
|---|---|---|
| Schedule | stock | pending schedules held at once |
| Deadline | stock | open and overdue deadlines held at once |
| Watch | stock | active watches held at once |
| Approval | flow | approval.request calls this month |
A recurring schedule counts as one, however many occurrences it fires.
The distinction is also a set of levers. A stock is something you can free up
without losing history: cancel a schedule; complete, cancel, or delete a
deadline; pause or delete a watch. Fired or cancelled schedules, 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.)
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.
Floors: how often things may happen
Each tier also sets two floors: minimum intervals rather than counts. Higher tiers have tighter floors. The exact floors are on the pricing page.
Poll-interval floor. If you request a Watch that
polls faster than your tier's floor, the interval is clamped up to the
floor — never rejected, never honoured below it.
Recurrence floor. A recurring Schedule whose
occurrences would fire closer together than your tier's floor is rejected,
not clamped: the create returns 422 with
{"error": "recurrence_too_frequent", ...}, and the message names the minimum
interval. Nothing is stored. Space the recurrence out, or upgrade. (A schedule
can't be quietly stretched the way a poll can, because the times you asked for
are the point of it.)
What happens at the limit
Every cap, stock or flow, rejects the same way: 429 Too Many Requests with
{"error": "tier_limit_exceeded", ...} naming the limit and your current and
maximum counts. On MCP the tool returns the same tier_limit_exceeded error.
A limit is never reported as a Conflict; that status is reserved for an action
that clashes with the state of one resource, such as cancelling a deadline that
is already complete.
Stock caps are enforced at create time. Calling schedule.create,
deadline.remember or watch.create while already at cap is rejected. Recover
by freeing a slot (cancel/complete/delete/pause) 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 the cap you're fine; inside
the grace band above it, requests still succeed but carry a warning (see
Seeing a limit coming); past the band you get the
429. The grace exists because agents don't batch neatly across a month
boundary. The free tier has no grace — every cap is hard. The size of the
grace band is on the pricing page.
Seeing a limit coming
When a paid request lands inside the grace band, it still succeeds, and the warning is raised once and reported on every surface:
- HTTP API: the response carries an
X-AIGears-Limit-Warningheader, e.g.usage 105% of monthly cap. - MCP: the tool result gains a
limit_warningfield with the same text. The field is absent when there is nothing to warn about. - Audit log: a
usage.soft_cap_warningevent is written alongside the request, so the warning is on record even if your agent ignored it. The Dashboard reads that event to show a banner for the rest of the month.
Whatever the surface, the Dashboard also shows your current usage against each cap, so you can see a limit approaching before it bites.
Audit retention by tier
How far back your history goes is also tier-bound: each tier keeps a retention window, and higher tiers keep a longer one. The window covers your audit log and the delivery history behind it — the webhook delivery attempts and the emails we sent on your behalf. See the pricing page for the window at each tier.
A nightly sweep enforces the window. Once a day it removes every audit event, webhook delivery and email delivery older than your tier's window. Nothing else ever deletes audit rows; the log is append-only the rest of the time.
A downgrade shortens the window. Moving to a tier with a shorter window means the next nightly sweep removes the history that falls outside it. That history does not come back if you upgrade again, so export anything you need to keep before you downgrade. Upgrading lengthens the window from then on.