Table of Contents

Configuring Quotas

Learn how to create and manage quotas in the Management Portal, and how to monitor quota events with the Quotas Analysis dashboard.

Overview

Quotas limit how much of the platform a user, a group, or the whole instance can consume. FoundationaLLM supports three quota types:

Quota type What it limits Example
Rate Limit Requests to a Core API controller, or requests that target an agent, within a short time window 100 completion requests per minute per user
Usage Limit Tokens consumed per month, for all agents or for one agent 1,000,000 tokens per month per user
Resource Limit The number of agents a user can own 5 agents per user

When a quota is exceeded, the API rejects the request with HTTP 429 (Too Many Requests) and returns the quota details. Rate limits also lock the caller out for the configured lockout duration.

Quotas have two pages in the sidebar:

  • Quotas > Quotas: create, edit, and delete quota definitions.
  • Quotas > Quotas Analysis: monitor quota health and recent quota events.

For the underlying model (contexts, partitions, and JSON properties), see the Quotas reference.

Prerequisites

  • Access to the Management Portal
  • The Quotas Contributor role. All quota operations, including viewing quotas and quota events, require this role. Other roles, including Owner, are not sufficient on their own.

Important: Quota definitions are loaded when the Core API starts. After you create, change, or delete a quota, restart the Core API for the change to take effect. The portal reminds you of this when you save.

View Quotas

  1. Sign in to the Management Portal.
  2. In the sidebar, select Quotas > Quotas.

The Quota Management page lists all quotas. Use Search quotas to filter by name, context, or type, and the Refresh (🔄) button to reload. The table is paginated (10, 25, 50, or 100 rows per page).

Column Description
Name The quota name.
Type The quota type and subtype, for example Rate Limit — API, Rate Limit — Agent, Usage Limit — Token, or Resource Limit — Agents.
Scope Shared (one limit for everyone covered by the quota) or Individual (a separate limit for each user).
Applies To The security principal the quota is scoped to, or All. Hover over a name to see the UPN when available.
Context The raw quota context, for example CoreAPI:Completions or Agent:__All__.
Limit For rate limits, {limit} / {window}s. For usage limits, {limit} / month. For resource limits, the maximum count.
Lockout The lockout duration for rate limits. Other types show —.
Actions View JSON definition (pi-code), a help icon (pi-question-circle) that describes the quota in plain English, Edit (pi-pencil), and Delete (pi-trash).

Create a Quota

  1. On the Quota Management page, select Create Quota.
  2. Fill in Common Settings.
  3. Fill in the settings section for the selected quota type (Rate Limit Settings, Usage Limit Settings, or Resource Limit Settings).
  4. Review the Summary panel on the right. If any field is invalid, the panel lists the problems under Fix these to save.
  5. Select Create Quota.
  6. In the Important dialog ("Changes will not take effect until the Core API service is restarted."), select OK.

Both sections can be collapsed and expanded by selecting their headers.

Common Settings

Field Description
Name Letters, numbers, dashes, and underscores. The portal checks availability as you type and shows ✔️ or ❌. The name cannot be changed after creation.
Description (optional) Notes about the intent of the quota.
Quota type Rate Limit, Usage Limit, or Resource Limit. The type cannot be changed after creation.
Metric limit The maximum number of requests (rate limit), tokens (usage limit), or resources (resource limit). Minimum 1. Maximum 10,000 for rate and resource limits, and 1,000,000,000 for usage limits.
Scope None (Shared): one limit shared by everyone covered by the quota. User Principal Name — UPN (Individual) or User Identifier (Individual): each user gets their own limit. Resource limits must be individual.
Applies to (optional) Scopes the quota to one security principal. Leave it empty to apply the quota to everyone. Select Select (or Change) to open the Browse Principals dialog.

In the Browse Principals dialog, choose a Search type (User, Group, or Service Principal), search in Search query, and select Select. The Agent Access Token search type appears only for rate limit and usage limit quotas that target a specific agent; it lists that agent's access tokens.

Shared quotas can only apply to a group or to everyone.

Rate Limit Settings

Field Description
Rate limit type API Controller Request Rate limits requests to a Core API controller. Agent Request Rate limits requests that target an agent.
Context API (CoreAPI) and Controller: Completions, CompletionsStatus, Sessions, Files, Branding, Configuration, UserProfiles, Status, or OneDriveWorkSchool. For Agent Request Rate, Agent (optional) narrows the quota to one agent; leave it blank for all agents. The raw context value is shown below the fields, for example CoreAPI:Completions:my-agent.
Quick presets (optional) Fills in Metric limit and Time window, for example 3 req / 60s (≈1 per 20s). You can edit the values afterward.
Time window 20 seconds, 40 seconds, 1 minute (60s), or 2 minutes (120s). A hint shows the effective rate per 20 seconds.
Lockout duration (seconds) How long requests are blocked after the quota is exceeded: 30, 60, 90, or 120 seconds.
Distributed enforcement When enabled, enforcement is synchronized across multiple API instances.

Rate limits are evaluated in 20-second buckets. A limit of 60 requests per 60 seconds allows about 20 requests in each 20-second bucket.

Tip: The User Portal polls CompletionsStatus frequently while a completion runs. Give CompletionsStatus a higher limit than Completions.

Usage Limit Settings

Field Description
Usage limit type Token Usage: limits the total number of tokens consumed.
Metric window Monthly. Usage resets at the start of each month.
Context Scope: All Agents (context Agent:__All__) or Specific Agent (context Agent:{agent name}). For Specific Agent, choose the agent in Agent name.

A shared usage limit (None (Shared)) that applies to All Agents must be scoped to a group in Applies to.

Resource Limit Settings

Field Description
Resource type Agents: limits the number of agents a user can own.

Resource limits are always individual, and they cannot apply to an agent access token.

Uniqueness Rules

For each context, the platform allows at most one quota in each of these combinations:

  • Shared with no principal
  • Individual with no principal
  • Shared for a given group
  • Individual for a given principal

Saving a quota that conflicts with an existing one fails with a message that names the existing quota.

Edit a Quota

  1. On the Quota Management page, select the Edit icon (pi-pencil) for the quota.
  2. Change the settings. Name and Quota type are read-only; use the copy button next to the name to copy it.
  3. Select Save Changes, and then select OK in the Important dialog.
  4. Restart the Core API.

Delete a Quota

  1. On the Quota Management page, select the Delete icon (pi-trash) for the quota.
  2. In the Delete Quota dialog ("Do you want to delete the quota "{name}"?"), select Yes.
  3. Restart the Core API.

Monitor Quotas with Quotas Analysis

  1. In the sidebar, select Quotas > Quotas Analysis.

The Quota Dashboards page refreshes every 30 seconds while Auto-refresh is on. Turn the switch off to stop automatic refresh, or select Refresh (🔄) to reload on demand. The time of the last update is shown at the bottom of the page.

Summary Cards

Card Description
Total Events (24h) Quota exceeded events from the last 24 hours, counted among the recent events the page loads.
Active Lockouts Reserved for active rate limit lockouts. This card currently always shows 0.
Events (7d) Quota exceeded events from the last 7 days, counted among the recent events the page loads.
Quota Health Score A score from 0 to 100 based on the average number of exceeded events per quota in the selected time range. 100 means no events.

Filters

  • Time Range: Last 24 hours, Last 7 days, or Last 30 days.
  • Quota: All Quotas or a single quota that has events in the time range.

Quota Health

The Quota Health table lists quotas that have events in the selected time range.

Column Description
Quota Name Select the name to open the quota in the editor.
Context The quota context.
# of Quota Exceeded events The number of exceeded events in the time range.
Health Status Good (2 or fewer events per day on average), Fair (up to 10 per day), or Poor (more than 10 per day).

Recent Events

The Recent Events table lists the most recent individual quota events in the selected time range, newest first.

Column Description
Timestamp When the event happened, shown as relative time (for example, "5 minutes ago").
Quota Name The quota that raised the event.
Context The quota context.
Partition The user the event applies to, or Global for shared quotas.
Event Type Quota Exceeded or Lockout Expired.
Count The count at the time of the event and the limit. Hover over the info icon for details: local and remote counts, the smoothing limit and 20-second smoothing interval, and the configured limit and interval.

Best Practices

  • Start with an individual rate limit on CoreAPI:Completions and a higher one on CoreAPI:CompletionsStatus.
  • Use Applies to with a group to give a team a different limit from everyone else.
  • Use usage limits to cap monthly token consumption per user, and per agent for expensive agents.
  • Review Quotas Analysis after changing limits. Quotas with Poor health may be set too low, or may indicate misuse.

Troubleshooting

Issue Resolution
A new or changed quota is not enforced Restart the Core API. Quota definitions are loaded at startup.
The Quotas pages show access errors Assign the Quotas Contributor role to the user.
Create Quota is disabled Fix the problems listed under Fix these to save in the Summary panel.
Agent Access Token is not offered in Browse Principals Select a specific agent in the rate limit or usage limit context first.
Users are locked out too often Increase Metric limit or Time window, or shorten Lockout duration (seconds).