Evaluate usage limit headroom
Evaluate the effective usage limits for a selector and return the current decision (AVAILABLE, WARNING, or BLOCKED) based on accrued usage. Requires usage:evaluate, without workspace billing permission. Omit target to evaluate the authenticated canonical user. An explicit USER must identify that user by canonical ID, known alias ID, email, or known alias email; every supplied field must identify the caller. An explicit AGENT requires current owner/editor or applicable global agent-edit permission; disabled agents remain eligible. Subagents, other users, ORGANIZATION, and default targets are forbidden on this route, even for billing administrators. Missing, inaccessible, and subagent targets return the same 403 insufficient_permissions. An explicit usage_selector.client_id selects the Glean or external spend client; it is never inferred from the caller. Agent evaluation reports aggregate agent usage, not the caller's personal slice or a complete run preflight. Returns only the target's own policies, such as user, default, department, IdP-group, and agent limits, with their values, used counters, decisions, and headroom; USD and credits have separate effective_limits. Shared budgets, such as the selected client's organization limit, are never itemized and never contribute values, counters, warnings, or headroom; a reached shared hard limit still makes decision BLOCKED and adds a decision_causes entry with budget_scope SHARED and its source_type. The response is the same for every caller, including billing administrators. IDP_GROUP sources always have is_identity_restricted true and no idp_group_id. Use the administrative route for shared-budget details. Evaluation reports configured-budget status even when runtime enforcement switches are off; it does not perform request admission, model eligibility, or agent-run preflight checks.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 413
- 429
- 500
- 503
Evaluation result.
Invalid request (malformed JSON, invalid parameter values, unknown fields).
Missing or invalid authentication token.
Token valid but lacks permission for the requested operation.
Resource not found.
Backend did not respond within the timeout window.
Request body exceeds the maximum allowed size.
Rate limit exceeded. Includes Retry-After header.
Unexpected server-side failure.
Backend temporarily unavailable.