Check customer entitlement
Whether the customer may consume requested more of a feature right now, given their
entitlement, the hard budgets that count the feature’s usage, and their prepaid credit.
Boolean features answer from their enabled state; config features grant access and return
their value. An ALLOW limit never refuses: in_overage tells when the requested units go
beyond it. Sliding windows send no threshold webhooks. Pass the group as
group[<property>]=<value>: it is required when the entitlement is grouped. Pass
subscription_id when the usage belongs to one subscription, so that a hard budget on another
subscription does not refuse it.
The answer reflects usage up to as_of: typically less than a minute old, and less than 10
seconds old once near_limit is true. A hard limit can therefore be exceeded by the usage of
those few seconds. While near_limit is true, check before every request with its actual
requested and do not cache the answer; retry_after_ms says when to check again. Use the
check to gate access, not to bill.
Beta: the request and response shapes of this endpoint may change before general availability.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Customer ID or alias
Feature ID or code
Query Parameters
Units the customer is about to consume. Defaults to 1.
The subscription (sub_…) the usage belongs to: only its own budgets and the customer-wide
ones apply. Without it, a budget on one subscription refuses only once every subscription
charging the feature's metric is refused by its own budget.
The group to check, as group[<property>]=<value>: required when the entitlement is grouped
Response
Whether the customer may consume the requested units
Whether a customer may consume more of a feature now.
When the usage behind the answer was measured.
Always false: the answer reflects usage up to as_of.
The entitlement allows overage (ALLOW) and the requested units go beyond its limit:
access is granted, and the overage is billed.
Age of that usage, in milliseconds.
Deprecated: always empty. Customer-specific limits are entitlement overrides, reported in
used, limit and remaining.
True when a hard limit is within 5% of being reached, reached, or refuses the request.
While true, check before every request with its actual requested, and do not cache an
answer that grants access.
WITHIN_LIMIT, LIMIT_REACHED, NO_ENTITLEMENT, DISABLED, BUDGET_EXCEEDED, INSUFFICIENT_BALANCE, TOO_MANY_GROUPS The current period of the entitlement's limit.
Units left before the limit, grace excluded: 0 while has_access is true when usage is
within the grace allowance.
When to check again, in milliseconds. After a refusal by a limit whose period ends within
24 hours: the time until it ends (a smaller requested may still be allowed sooner);
absent after a refusal by a sliding window, whose usage leaves it gradually. While
near_limit is true and access is granted: 1000.
used, limit, remaining and period report the entitlement's limit. Absent when the
entitlement has no limit.
The value of a CONFIG feature.
- Option 1
- Option 2
- Option 3
- Option 4