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-Warning header, e.g. usage 105% of monthly cap.
  • MCP: the tool result gains a limit_warning field with the same text. The field is absent when there is nothing to warn about.
  • Audit log: a usage.soft_cap_warning event 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.