Querying Salesforce Usage-Based Entitlements with SOQL

Understanding TenantUsageEntitlement

Salesforce usage-based entitlements are features or functionalities your organization can access on a periodic basis. Unlike permanent licenses, these entitlements track consumable resources, such as API calls, flow interviews, or storage that reset based on your contract terms. The challenge many Salesforce administrators face is the lack of public documentation about programmatically querying this data, but the TenantUsageEntitlement object is the key to unlocking usage insights.

The TenantUsageEntitlement Object

The TenantUsageEntitlement object represents a data structure containing information about the features and functionalities your Salesforce org is entitled to access. This object has been available since API version 28.0 and supports standard operations including query(), retrieve(), describeSObjects(), and describeLayout().

SOQL Query Example

Here's the practical SOQL query to retrieve usage-based entitlement data from your org:

SELECT Id, MasterLabel, ResourceGroupKey, Setting, CurrentAmountAllowed, AmountUsed, StartDate, EndDate, Frequency, HasRollover, OverageGrace, UsageDate FROM TenantUsageEntitlement

Field	Purpose
Id	Unique identifier for the entitlement record
MasterLabel	Human-readable name of the entitlement (e.g., "API Request Limit per Month")
ResourceGroupKey	Internal identifier for grouping related resources
Setting	Configuration or type setting for the entitlement
CurrentAmountAllowed	Your organization's current allocation for this resource
AmountUsed	Actual consumption of this entitlement in the current period
StartDate	Beginning of the entitlement period
EndDate	End of the entitlement period
Frequency	How often the entitlement resets (e.g., monthly, yearly)
HasRollover	Boolean indicating if unused allocations carry over to the next period
OverageGrace	Grace period allowance if usage exceeds the limit
UsageDate	Date tracking for usage metrics