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 and the selected client's organization limit, not the caller's personal slice or a complete run preflight. All applicable limit values, used counters, decisions, and headroom are returned; USD and credits have separate effective_limits. IdP-group source identities require billing-read permission. Other callers receive an IDP_GROUP source with is_identity_restricted true and no group_id, without suppressing the policy's value, counter, or decision. 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.