Credits and usage

AI credits

Every LLM call is recorded with its token counts. ZeroReach turns tokens into credits with each model's weight from the model catalog:

credits = round((input_tokens + output_tokens) × weight / 1000)

Credits are computed on the summed tokens of a group (a message, a model, a day), never per call, so small calls aren't rounded away. Free-tier models count credits too.

Limits

Both 429 answers carry Retry-After. A value of 0 turns the monthly cap off; a daily limit of 0 turns the assistant off.

People see their usage in the app under Settings → AI models and usage: this month, last month or the last 7, 30 or 90 days, by feature, model, person and day, with a CSV export. Admins see the whole workspace; a member sees only their own usage (GET /api/v1/workspaces/current/ai-usage?period=current).

Alerts, member limits and estimates

How other credit-based products handle caps, and what ZeroReach took from them, is in docs/research/12-credits-market-patterns.md.

• Alerts. Admins choose up to four thresholds (percent of the monthly allowance; default 80 and 100) with PUT /api/v1/workspaces/current/ai-credits. The first time this month's credits pass one, the admins get an in-app notification (ai_credits_threshold), once per threshold and month. The app shows a banner near and at the cap.
• Member limits. Admins set a default monthly limit per member and per-member overrides (PUT /api/v1/workspaces/current/ai-credits/members/{user_id}). They are hard: past their limit a member's new AI work answers 429 with the code ai_credits_user_limit and Retry-After. Others keep working.
• Estimates. POST /api/v1/ai-credits/estimate with action research_batch (and items) or discovery_run answers "about N credits" from the same formula, with what's left this month and a warning when it may not fit. Zero and MCP clients can call it as estimate_ai_credits; get_ai_credits reads the month's status.
• At the cap. Nothing is reserved. A job that has started finishes the item it's on, then waits for the reset: a research batch pauses until the 1st, a discovery run keeps what it found. Nothing retries in a loop.
• Later. Top-ups, auto top-up and rollover come with paid plans.

Models

The model catalog lists the models Zero can offer, with their speed, quality, credit weight and lifecycle (ga, preview, deprecated or retired).

• On the platform's keys, only free-tier models are offered. A workspace that brings its own LLM provider (admins, /api/v1/settings/providers) gets only that provider's models, with its own key.
• Models whose free tier may train on prompts are never offered by default. An admin must add them explicitly, after a warning.
• A retired model is never used. A chat on a retired model moves to its replacement, else the workspace default, and says why.

Budgets behind AI features

Every external AI or data call has a request budget and fails closed: when a quota is used up or a provider answers 429, the feature stops instead of retrying in a loop or falling back to a paid provider.

Platform admins can see today's AI request counts against the free-tier budgets with GET /api/v1/ai/usage. The counts are app-wide.