Feature filters let you restrict a credit grant to specific product features and query balances or transaction history scoped to a single feature.
Use them when you need to track or display how much credit is available for a particular feature, such as input_tokens or output_tokens.
Feature filters
Uses:
Metering & Billing
Related Documentation
Incompatible with
on-prem
How feature balances work
A feature balance represents the total credit available for a specific product feature.
The available balance includes the following types of credits:
- Restricted credits: Can only be consumed by charges for the features listed on the grant.
- Unrestricted (shared) credits: Have no feature restriction and can be consumed by any feature.
A feature balance includes both restricted credits for that feature and unrestricted shared credits, because both are available to spend on it. Not all credit in a feature balance view is restricted to that feature.
You can apply only one operator to filter[feature_key] per request.
Restricting grants to features
When you create a credit grant, filters.features controls which features can use that credit.
|
|
Meaning |
|---|---|
| Omitted or empty | The credit is unrestricted and can be used for any feature. |
["input_tokens"]
|
The credit can only be used for the specified feature, for example: input_tokens.
|
["input_tokens", "output_tokens"]
|
The credit can be used for any of the listed features. |
Querying by feature
Use filter[feature_key] to scope a query to one or more features.
The filter syntax is the same for the balance and transaction endpoints.
|
Operator |
Syntax |
Returns |
|---|---|---|
| None (omitted) | — | All credits or transactions, regardless of feature. |
eq
|
filter[feature_key][eq]=input_tokens
|
Credits or transactions relevant to input_tokens, including shared unrestricted credits.
|
oeq
|
filter[feature_key][oeq]=input_tokens,output_tokens
|
Credits or transactions for any of the listed features. |
neq
|
filter[feature_key][neq]=input_tokens
|
Credits or transactions not matching the specified feature, for example: input_tokens..
|
contains
|
filter[feature_key][contains]=tokens
|
Credits or transactions where the feature key contains the string. |
ocontains
|
filter[feature_key][ocontains]=input,output
|
Credits or transactions where the feature key contains any of the strings. |
When you query by feature, the balance or transaction results include:
- Unrestricted shared credits
- Credits restricted to that specific feature
- Credits restricted to a set that contains that feature
For example, using filter[feature_key][eq]=input_tokens:
|
Credit grant |
Included in |
|---|---|
| Unrestricted | Yes |
["input_tokens"]
|
Yes |
["input_tokens", "output_tokens"]
|
Yes |
["storage"]
|
No |
Examples
In the following examples, replace {customerID} with the customer’s ID.
The customer name and key aren’t accepted in this path parameter.
To find a customer ID, send a GET request to the /openmeter/customers endpoint, or check the URL of the customer’s profile in the Konnect UI.
Filter parameters must be percent-encoded in the URL: use %5B for [ and %5D for ].
For example, filter[feature_key][eq] becomes filter%5Bfeature_key%5D%5Beq%5D.
Query the credit balance for a specific feature:
curl -X GET "https://us.api.konghq.com/v3/openmeter/customers/{customerID}/credits/balance?filter%5Bfeature_key%5D%5Beq%5D=input_tokens" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN"Query the transaction history for a specific feature:
curl -X GET "https://us.api.konghq.com/v3/openmeter/customers/{customerID}/credits/transactions?filter%5Bfeature_key%5D%5Beq%5D=input_tokens" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN"