Usage & quotas

How usage governance works

MagOneAI meters AI consumption in tokens — the units a language model reads and writes — not in dollars. Every quota you set is a cap on how many tokens can be consumed within a time window. This keeps governance predictable across providers and models, and it works the same whether a model is expensive or cheap.

You use two complementary controls:

---

Quota periods

Every quota runs on a fixed window in UTC:

Windows reset automatically at the period boundary — there's no manual reset to perform and nothing to remember to clear. When a new period begins, used-token counters return to zero and the full allowance is available again.

---

What a quota can apply to

A limit can be attached to any of these scopes, so you can govern broadly or precisely:

Limits cascade

Quotas resolve from the broadest setting down to the most specific:

1. A platform default applies if nothing more specific is set.
2. An organization default can override the platform default.
3. A specific scope limit (project, use case, or per-user) can override the defaults for that scope.

This means you can set one sensible default and then carve out exceptions only where you need them.

Cap a single model

Any limit can optionally apply to just one model (one LLM configuration) instead of all usage. This lets you put a tight cap on an expensive model while leaving cheaper models more headroom — without restricting overall usage.

Finite or unlimited

Each limit is either:

• A finite token budget for the period, or
• Unlimited — usage is still fully tracked and visible, but it is never blocked.

---

How enforcement decides

When several limits apply to the same request — say an org cap, a project cap, and a per-user cap — MagOneAI uses most restrictive wins. The request must satisfy all applicable limits; it's allowed only if every one of them still has room.

When a request is blocked

If a request would exceed a limit, the LLM call is blocked before it runs, and the member sees a clear message that names:

• Which scope was hit (organization, project, use case, or their own per-user limit),
• The limit and the period it applies to, and
• The model, if the limit was model-specific — so the member knows they can switch to a different model and continue.

Fail-open

If the usage-tracking system is briefly unavailable, MagOneAI lets requests through rather than blocking your teams. Governance favors keeping you working over hard-failing during a transient outage; enforcement resumes automatically once tracking is back.

---

Top-ups

Sometimes a team needs more room within a period without you changing the base limit. An admin can grant a top-up — extra token credits added on top of the base allowance.

• Top-ups stack on the base limit for the period, raising the effective cap.
• A top-up can carry an optional expiry date, after which it no longer counts toward the allowance.

Top-ups are the mechanism behind approved limit-increase requests (below), and you can also grant them proactively.

---

Self-serve limit-increase requests

When a member is blocked, they don't have to file a ticket and wait — they can request a higher limit directly on the scope that blocked them. An admin then reviews and decides.

A request moves through these states:

---

Seeing usage

Everyone gets visibility appropriate to their role.

Because every view shows the reset time, it's easy to tell whether a team is genuinely over-provisioned or simply close to the end of a busy period.

Prompt-cache accounting

When a provider serves part of a prompt from its prompt cache, MagOneAI records those tokens separately so cache activity is visible, not hidden inside the totals:

• Cache-read tokens — input tokens served from the provider's cache instead of being reprocessed.
• Cache-write tokens — input tokens written to the cache on this request (Anthropic models).

These cache tokens are a subset of input tokens — they count toward quotas exactly as input tokens do, and nothing is counted twice. Usage summaries also surface a cache-hit percentage, so you can see how effectively caching is trimming reprocessing on repetitive prompts.

---

Threshold notifications

Separate from enforcing quotas, an organization can set a daily token threshold that triggers notifications to platform admins as usage climbs:

---

The "Auto" model picker

The per-turn model picker in both the workflow Builder and MagOneAI Hub now defaults to Auto (default assigned model).

• Auto sends no model override, so each agent runs on its own assigned model — exactly as the workflow was designed.
• Choosing a specific model is an explicit, per-turn opt-in. Selecting Auto again returns to the default.

This pairs naturally with per-model quotas: if an expensive model is capped for the period, you can pick a cheaper model for that turn and keep working, then fall back to Auto when you're done.

---

Good patterns

• Default broad, restrict narrow. Set a comfortable org default, then add tighter project, use-case, or per-user limits only where you need them. The cascade does the rest.
• Cap the expensive model, not everything. A model-specific limit on a premium model contains your biggest costs while leaving everyday work unaffected.
• Use threshold notifications as a tripwire. Pair a daily threshold with your quotas so admins hear about heavy days at 75% — well before anyone hits a hard block.
• Prefer top-ups for short-term needs. When a team needs more room for a busy period, grant a top-up with an expiry rather than permanently raising the base limit.

---

Next steps