Usage API

The Platform Usage API lets billing administrators configure and inspect usage limits, and lets users and agent editors check their headroom and request more.

Use Cases

Usage Settings

Read the workspace-wide usage policy that Billing uses.

Usage Limits

List, create or replace, reset, and batch-apply limits for the organization, users, IdP groups, departments, and agents.

Limit Evaluation

Return the current decision (AVAILABLE, WARNING, or BLOCKED) for a target, based on accrued usage.

Limit-Increase Requests

Let users and agent editors ask for more headroom, and let billing administrators approve or deny those requests.

API Endpoints

Method	Endpoint	Purpose
GET	/api/admin/usage/settings	Get usage settings
PATCH	/api/admin/usage/settings	Update usage settings
GET	/api/admin/usage/limits	List usage limits
POST	/api/admin/usage/limits	Upsert a usage limit
POST	/api/admin/usage/limits/reset	Reset a usage limit
POST	/api/admin/usage/limits/batch	Apply usage limit policies
POST	/api/admin/usage/limits/evaluate	Evaluate administrative usage limit headroom
POST	/api/usage/limits/evaluate	Evaluate usage limit headroom
POST	/api/usage/limit-increase-requests	Submit a personal limit-increase request
GET	/api/usage/limit-increase-requests	List personal limit-increase requests
GET	/api/usage/limit-increase-requests/{request_id}	Get a personal limit-increase request
POST	/api/admin/usage/limit-increase-requests	Submit an editable-agent limit-increase request
GET	/api/admin/usage/limit-increase-requests	List the billing limit-increase request queue
GET	/api/admin/usage/limit-increase-requests/{request_id}	Get a billing limit-increase request
PATCH	/api/admin/usage/limit-increase-requests/{request_id}	Resolve a billing limit-increase request

Administrators evaluate any target with POST /api/admin/usage/limits/evaluate. Users evaluate themselves, or an agent they can edit, with POST /api/usage/limits/evaluate.

Administrative operations require permission to read or edit workspace billing in addition to their OAuth scope. A global administrator role is not required.

Every Usage endpoint except POST /api/admin/usage/limits is experimental. Send X-Glean-Include-Experimental: true on each request, or they are not exposed.

Use the Users, Departments, IdP Groups, and Agents APIs to find the identifiers that usage limit targets use.

For error responses, see Platform API Errors for the shared ProblemDetail code reference and remediation guidance.