Skip to Content
Deploy & Operate📊 Usage Quotas

Usage Quotas

An instance admin can limit how much each user spends on language models. A quota has two independent budgets:

  • Tokens — prompt plus generated tokens. Works for every model, including local ones.
  • Cost (USD) — tokens priced at the model’s catalog rate. Only sees models that declare a price.

Set either, both or neither. Quotas are managed from Admin → Quotas, or through the API. With no quota set, nothing is limited.

ℹ️

Quotas need an instance admin, which exists only under AUTH_TYPE=oidc (or in a single-user install with no authentication and LOCAL_MODE_ADMIN=true). Under simple_jwt, the default for docsgpt up --expose network and --domain, nobody can manage quotas, and every request counts as the one shared user local, so per-user and per-team limits cannot tell people apart. See Access Control.

Layers

Limits are set at three layers. For each budget, the first layer that says something wins:

  1. User override — one user’s own limit.
  2. Team allowance — what each member of a team gets.
  3. Instance default — everyone else.

At each layer a budget is either not set (defer to the next layer), a limit, or unlimited. A limit of 0 blocks the user. The two budgets resolve separately, so a user’s token limit can come from their team while their cost limit comes from the instance default.

Teams

A team allowance is per member, not a pool the team shares: if the allowance is 2M tokens, each member may use 2M.

A user in several teams gets the most generous allowance among them, and allowances are never added together. Usage is always counted per user, whichever teams they belong to. To hold one person below their team’s allowance, give them a user override.

ℹ️

Team membership can change without an instance admin — team admins add members; OIDC group sync and SCIM don’t. The most generous team allowance applies, so joining another team can’t lower a limit a user already gets from a team; but a team allowance overrides the instance default, so a team below the default lowers its members’ limit. Only instance admins set allowances; team admins cannot.

Windows and enforcement

Usage is counted over a calendar window in UTC, chosen for the whole instance with QUOTA_PERIOD: day (from 00:00), week (from Monday) or month (from the 1st, the default). Windows are worked out when a request arrives, so there is no reset job to run.

The quota is checked before a run starts, and again before every model call of the run, so an agent in a long tool loop stops at the limit rather than after it. The call that crosses a limit completes; the next one is refused. A guardrail judge’s call is the exception: it counts, but it is never refused, so the answer that crossed the limit is still checked. A request refused before it starts gets HTTP 429:

{ "success": false, "error_code": "quota-exceeded", "message": "Usage quota reached (1,000,000 of 1,000,000 tokens). It resets at 2026-10-01T00:00:00+00:00.", "limit_scope": "user_quota", "dimension": "tokens", "unit": "tokens", "usage": 1000000, "limit": 1000000, "bucket": "all", "source": "instance", "resets_at": "2026-10-01T00:00:00+00:00" }

The response carries a Retry-After header with the seconds until the reset, and x-should-retry: false so the OpenAI SDKs don’t retry with backoff. dimension is tokens or cost; for cost, usage and limit are in USD. The check covers chat, the agent and OpenAI-compatible APIs, scheduled runs, webhook runs and Draft with DocsGPT. If the quota check itself fails, the request is allowed.

When a limit is reached during a run:

  • A chat stops where it is, keeps the partial answer, and says that the allowance is reached and when it resets.
  • A scheduled run is recorded as failed with payer_out_of_allowance and keeps its partial output. Later runs are skipped while the payer is out of allowance; see Paid by and paused schedules.
  • A webhook run ends with what it did so far and "status": "agent_paused" for the payer’s allowance (the caller learns nothing more), or "status": "quota_exceeded" for the agent’s own limit; see Agent webhooks.

Who pays

Whoever starts a run pays for it, from their own quota. Where an agent lives and who owns it don’t decide it.

TrafficCharged to
A chat, with or without an agent, in Personal or in a team workspace, including a signed-in visitor chatting through an agent’s public linkThe person chatting
A schedule’s runsThe person the schedule is stored under, shown as Paid by on it (see Who owns a schedule)
An agent’s API key and widget, webhook, /v1 and MCP traffic, and public-link visitors who aren’t signed inOn a personal agent, its owner. On a team agent, the Admin who turned its outside access on, or who took it over
A background continuation, a retry, a chat’s title, a workflow step, a sub-agentWhoever pays for the run it belongs to
Draft with DocsGPTThe person drafting, as chat without an agent
A graph built from a source (GraphRAG)The person adding or syncing the source

Per-agent token and request limits still apply on top of the payer’s quota. A team has no budget of its own: a team allowance is what each member gets, and the team’s Usage tab reports what the workspace used without limiting it (see Usage).

Embeddings, OCR and speech-to-text aren’t counted against any quota.

What people see

  • From 80% of an allowance, a line above the chat input says how much is used and when it resets.
  • At 100%, the chat shows a card in its place: the period, what the allowance covers, and what of the person’s has stopped, such as “2 schedules you set are paused” or an agent they pay for that has stopped answering through its API key. Sending stays off until the allowance resets or an admin raises it.
  • Settings → Analytics shows one meter for the period, split into the person’s chats, the schedules they set, the agents they published and other use (see Analytics and Logs).

Outside callers

When the payer of an agent’s outside access is out of quota, people reaching the agent through its API key, widget, webhook, /v1 or MCP, or through its public link without signing in, are told only that the agent is paused. They never see the payer’s usage, limit or reset. A signed-in visitor on the public link pays for their own chat, so only their own quota stops them, with the usual message:

{ "success": false, "error_code": "agent_paused", "code": "agent_paused", "message": "This agent is paused, so it can't answer right now." }

It is a 429 with Retry-After set to the reset and x-should-retry: false. On /v1 the body has the OpenAI error shape the API’s other errors use: {"error": {"message": "...", "type": "rate_limit_error", "code": "agent_paused"}}. A run stopped part way for the same reason ends with the same code and message. The agent’s own limit keeps its own message, which is about the agent, not a person. The same agent_paused refusal, as a 403, answers outside callers while the payer’s account is deactivated or, on a team agent, while the payer is no longer an Admin there. A team agent whose outside access has nobody to pay for it answers no_payer.

Pricing

Cost budgets use the rates in the model catalog, in USD per million tokens:

models: - id: my-model input_cost_per_million: 3.0 output_cost_per_million: 15.0 cached_input_cost_per_million: 0.3 # optional, prompt-cache reads cache_write_cost_per_million: 3.75 # optional, prompt-cache writes

The built-in catalogs ship list prices for hosted models. Override or add rates by dropping a YAML with the same model id into MODELS_CONFIG_DIR. The cost of each call is stored with its usage row when the call is made, so later price changes do not rewrite history.

⚠️

A model with no declared price is recorded at $0, so a cost budget cannot see it. The Quotas tab lists such models once they have been used. Either limit them with a token budget, declare their rates, or set QUOTA_UNPRICED_RATE_PER_MILLION to charge a fallback rate. Custom models, added by a user or a team with their own API key, are always $0, but their tokens still count.

API

Every admin endpoint requires the admin role, and every change is written to the audit log as quota_policy_set or quota_policy_deleted.

MethodPathDescription
GET/api/admin/quotasAll policies by layer, the current window, and used models without a price.
PUT DELETE/api/admin/quotas/instanceThe instance default.
GET PUT DELETE/api/admin/quotas/teams/<team_id>A team’s per-member allowance.
GET PUT DELETE/api/admin/quotas/users/<user_id>A user’s override; the user must already exist (SCIM-provisioned, or signed in once), otherwise 404. GET also returns the limits the user ends up with, the layer each came from, and their usage.
GET/api/user/quotaThe caller’s own limits, usage and reset time. With a limit set it also returns notice ({level, percent, bucket, budget, resets_at} from 80% used, level near or reached; otherwise null) and parts (this period’s use as chat, schedule, published and other), and once a limit is reached, paused ({schedules, published}: what the caller pays for that has stopped; a public_link in an agent’s access has stopped only for visitors who aren’t signed in).

A PUT body sets, per budget, a limit or the unlimited flag; leave both out to defer to the next layer:

{ "token_limit": 2000000, "cost_unlimited": true, "note": "Research team" }
FieldTypeDefaultDescription
token_limitinteger or nullnullToken budget per window. 0 blocks the user.
token_unlimitedbooleanfalseNo token limit at this layer.
cost_limit_usdnumber or nullnullCost budget per window, in USD (stored to 4 decimal places). 0 blocks the user.
cost_unlimitedbooleanfalseNo cost limit at this layer.
enabledbooleantruefalse keeps the policy but ignores it, so the next layer applies.
bucketstringallall, direct or agent (see below).
notestringnullFree text, up to 500 characters.

A PUT replaces the whole policy for that layer and bucket, so send every field you want to keep. It returns 400 when a budget has both a limit and its unlimited flag set, when neither budget has a limit or an unlimited flag (delete the policy instead), when a value has the wrong type or is out of range (negative or too large), or when bucket isn’t one of all, direct or agent.

bucket (default all) narrows a policy to direct traffic (chat without an agent) or agent traffic (anything that runs through an agent, whether or not the agent has an API key). A request must fit both its own bucket and all. The dashboard edits all.

Last updated on