Table of Contents

Quotas

Reference information for FoundationaLLM quota definitions.

Overview

A quota is a resource managed by the FoundationaLLM.Quota resource provider. Each quota defines a limit on one metric, the context the limit applies to, how the metric is partitioned between users, and, optionally, the security principal the quota is scoped to.

There are three quota types, identified by the type property:

type Portal label Subtypes (quota_type) Enforced on
rate-limit-quota Rate Limit APIControllerRequestRate, AgentRequestRate Requests to Core API controllers, and completion requests that target an agent
usage-limit-quota Usage Limit TokenUsage Tokens consumed by completion requests (including realtime speech turns) in the current month
resource-limit-quota Resource Limit Agents, Sandboxes The number of agents or sandboxes a user owns, checked when a new one is created

The Management Portal creates Agents resource limits only. Sandboxes resource limits are supported by the resource provider but are not offered in the portal.

Quota definitions are loaded when the Core API starts, so changes take effect after the Core API restarts. To manage quotas in the portal, see Configuring Quotas.

Common Properties

Property Description
type The quota type: rate-limit-quota, usage-limit-quota, or resource-limit-quota.
name The quota name. Letters, numbers, dashes, and underscores.
description Optional description.
context What the quota applies to. The format depends on the quota type (see below).
quota_type The subtype for the quota type.
metric_partition None (shared: one counter for everyone covered by the quota), UserPrincipalName, or UserIdentifier (individual: one counter per user).
metric_limit The limit. Must be greater than 0.
principal_type Optional. User, Group, ServicePrincipal, or AgentAccessToken. Must be set together with security_principal_id.
security_principal_id Optional. The object ID of the user, group, or service principal, or the agent access token ID. Must be a GUID.

Security Principal Rules

  • Without a principal, the quota applies to everyone covered by the context.
  • A Group principal applies to callers who are members of the group, including agent access token callers through the agent's virtual security group.
  • Shared quotas (metric_partition = None) can only use a Group principal or no principal.
  • AgentAccessToken scopes an individual quota to a single agent access token. It is valid only for rate limit and usage limit quotas.

Uniqueness Rules

Within one context, at most one quota can exist for each of these combinations: shared with no principal, individual with no principal, shared for a given group, and individual for a given principal. A conflicting quota is rejected with HTTP 409.

Rate Limit Quotas

Property Description
quota_type APIControllerRequestRate or AgentRequestRate.
context CoreAPI:{controller} or, to scope the quota to one agent, CoreAPI:{controller}:{agent name}.
metric_window_seconds The time window: 20, 40, 60, or 120.
lockout_duration_seconds How long the caller is blocked after exceeding the quota: 30, 60, 90, or 120.
distributed_enforcement true to synchronize enforcement across multiple API instances.

Valid controller names are Branding, Completions, CompletionsStatus, Configuration, Files, Management, OneDriveWorkSchool, RealtimeSpeech, Sessions, Status, and UserProfiles. The portal offers all of these except Management and RealtimeSpeech.

Rate limits use a 20-second smoothing window. The effective limit per 20 seconds is metric_limit / (metric_window_seconds / 20). Choose a metric_limit that divides evenly; for example, 60 requests per 60 seconds allows 20 requests per 20 seconds.

The User Portal polls the CompletionsStatus controller frequently while a completion runs. Give it a higher limit than Completions.

Example

{
    "type": "rate-limit-quota",
    "name": "coreapi-completions-per-user",
    "description": "120 completion requests per minute per user.",
    "context": "CoreAPI:Completions",
    "quota_type": "APIControllerRequestRate",
    "metric_partition": "UserPrincipalName",
    "metric_limit": 120,
    "metric_window_seconds": 60,
    "lockout_duration_seconds": 60,
    "distributed_enforcement": false
}

Usage Limit Quotas

Property Description
quota_type TokenUsage.
context Agent:__All__ for all agents, or Agent:{agent name} for one agent.
metric_window_type Month. Usage resets at the start of each month.

A shared usage limit for all agents (metric_partition = None and context = Agent:__All__) must have a Group principal.

Example

{
    "type": "usage-limit-quota",
    "name": "monthly-tokens-per-user",
    "context": "Agent:__All__",
    "quota_type": "TokenUsage",
    "metric_partition": "UserPrincipalName",
    "metric_limit": 1000000,
    "metric_window_type": "Month"
}

Resource Limit Quotas

Property Description
quota_type Agents or Sandboxes.
context Must equal quota_type: Agents or Sandboxes.

Resource limits must be individual (UserPrincipalName or UserIdentifier) and cannot use an AgentAccessToken principal.

Example

{
    "type": "resource-limit-quota",
    "name": "max-agents-per-user",
    "context": "Agents",
    "quota_type": "Agents",
    "metric_partition": "UserPrincipalName",
    "metric_limit": 5
}

Quota Exceeded Behavior

When a quota is exceeded, the request is rejected with HTTP 429 (Too Many Requests). For rate limits and usage limits, the response body contains the quota evaluation result, including quota_exceeded and quota_details. For rate limits, the caller stays locked out for lockout_duration_seconds. For resource limits, the create request fails with HTTP 429 and an error message.

Quota Events

The platform records quota events, which the Quotas Analysis page displays.

Quota type Event types
Rate limit quota-exceeded, lockout-expired
Usage limit quota-exceeded, quota-recovered
Resource limit quota-exceeded, quota-recovered

Permissions

All operations on quotas, quota metrics, and quota events require the Quotas Contributor role. This role is mandatory: other roles, including Owner, do not grant access to quotas on their own. See the Permissions Reference.