Usage limits

An organization can set usage limits: at most so many credits used in a day and in a month, for the whole organization and, separately, for each workspace. Both are optional. The day is the calendar day in UTC and the month the calendar month in UTC, from the 1st — not the billing period. Every limit that applies counts, and the first one reached stops new work: a workspace can hit its own limit while the organization still has room, and the other way round.

A usage limit is not the balance. An organization can have plenty of credits and still be stopped by a limit; buying credits does not lift it. Usage limits are not the AI safety limits either: those are set by Madoo on AI generation and answer ai_spend_paused.

What counts

“Used” is what was consumed in the day or the month plus what the runs still in progress have reserved. A run reserves its estimated cost when it starts, so ten runs submitted at the same instant cannot all pass a limit that only has room for one. A reservation that a finished run gives back stops counting at once.

Work that was already admitted always finishes and is always billed. That is why a limit can be passed by a little: a step priced while it runs can cost more than its reservation, a run reserved before midnight is billed on the day it is billed, and the AI assistant and Madoo AI know their cost only after they answer. A day can therefore start above its limit — new work waits for the next day, nothing else changes.

When a request is refused

Every new reservation is checked against the limits: starting a run (editor, REST API, MCP, apps, embeds, batches, runs started by Madoo AI), retrying one, a new item of a list, a sub-workflow, a new attempt of Repeat until accepted, a step priced at run time, and each request to the AI assistant or Madoo AI.

• At submission the answer is 402 credit_cap_reached (CREDIT_CAP_REACHED on the internal API). The details say which limit (scope: organization or workspace, period: day or month), the limit, what is used, what the request needed and when the period ends (resets_at_utc). When the balance would not have covered the request either, they say so as well; the limit is still what is reported, because credits would not help. REST: Executions §1.3; MCP: the execute_workflow error carries the same details.
• During a run a refused reservation stops the whole run with CREDIT_CAP_REACHED. What it already produced is kept and the unused reservation is returned. In a batch, the items not started yet are cancelled with the same code.

Do not retry the same request in a loop: it is refused until the period ends or the limit is raised. Tell the person when work can start again — resets_at_utc, next 00:00 UTC for a daily limit, the 1st of next month for a monthly one — and that an owner or admin of the organization can raise the limit. A run that costs nothing at a known price is never refused.

Warnings

When a limit reaches 80 % of its consumed credits, and when it is reached (the first refusal), Madoo e-mails the organization’s owners and billing contacts — plus the workspace’s admins for a workspace limit — and shows them a notification in the app. Each warning is sent once per limit and per day or month; a changed limit starts them again. In the app, the credit badge at the bottom left shows a row for today and one for this month, with how much of the limit is used.

Who changes a limit

Only an owner or admin of the organization, in Settings → Billing → Usage limits: daily and monthly, in whole credits, for the organization and for each workspace; empty means no limit. Every member can see the limits that apply to them. A new limit applies from the next reservation; a limit lowered below what is already used stops new work at once, while runs in progress finish what they reserved. Madoo support can change a limit when the organization asks; there is no way to run past a limit.

Limits cannot be read or changed through the public API or MCP. An agent that is refused should report the refusal and its details, not look for a way around it.