Skip to main content

​
Tracking Usage

To monitor customer usage and enforce limits or billing, record each usage event with Metrifox. Send Usage Events Use the RecordUsage method to log consumable feature usage, such as AI image generations or API calls. You always record usage in feature units (e.g. number of API calls) — never in credits.
Credits are never recorded or deducted directly. A feature is credit-based when it is priced as prepaid with a credit cost (e.g. 1 API call = 0.02 credits). When you record usage for that feature, Metrifox adds to the consumed count and automatically deducts the equivalent credits from the wallet funding it (4 API calls → 0.08 credits deducted).
Before recording usage, it’s best to verify that the customer is entitled to use the feature. This helps prevent:
  • Exceeding usage limits
  • Unauthorized access
  • Unintended overage charge
Each time a customer uses a feature:
  1. Call theRecordUsage
  2. Include relevant metadata (e.g. feature Key, quantity, timestamp)
  3. Metrifox updates the customer’s usage balance accordingly
This ensures accurate enforcement of quotas, overage billing, and usage-based pricing.
Features aggregated with COUNT_UNIQUE must carry their aggregation property values on every event, under a top-level properties object (e.g. "properties": { "account_id": "acct_1" }). An event that omits a configured property is rejected. See Understanding Features for how distinct values are counted.

SDK available in

Javascript | Ruby | cURL | Python | PHP | Go | Java

​
Correcting a Recorded Event

Recorded an event that was wrong? Correct it with POST /usage/events/adjust using the original event_id. Send the actual amount the customer used — sending the same value again is a safe no-op. Used less — refund the difference (recorded 5, actually used 4):
Used more — charge the difference (recorded 200 credits, actually used 250):
Undo it — leave the amounts out:
See Adjust a Usage Event for details.

​
Adjusting Usage Counts for Persistent Features

For persistent-use features — features that represent a standing count rather than one-off consumption, such as seats or licenses — you can decrement the recorded usage count by sending a negative value with RecordUsage. This only applies to persistent features. It does not apply to consumable/event-style usage, and it does not add credits to a customer. Use Case: Reclaiming Seats If a customer is using 8 seats and removes one, send a quantity of -1. Metrifox updates their usage count from used: 8 to used: 7, which frees up their available allowance for that feature (available = allowance − used).

​
On a COUNT_UNIQUE feature, a negative quantity releases one value

The example above subtracts an amount, because a SUM feature adds up the quantity you send. A COUNT_UNIQUE feature counts distinct values instead, so a negative quantity releases one value — the one named in properties. Only the sign is read. The number itself is ignored. Send the same properties values you counted it with:
That releases acct_1 and takes the count from used: 8 to used: 7. Sending -7 here does exactly the same thing: it releases acct_1, and nothing else. It does not subtract 7. To release three accounts, send three events, one for each account. Once released, acct_1 counts again the next time you send an event carrying it.
Releasing is only possible on a persistent-use COUNT_UNIQUE feature. On a per-use one a negative quantity is rejected, because its counted values are already cleared at the end of every period — there is nothing to release by hand.If you counted a value you should not have, adjust that event to 0 instead. That works on both usage models, and on a COUNT_UNIQUE feature it frees the value to be counted again.
This adjusts the usage count of a persistent feature only. To add credits to a customer, use a credit topup — recording negative usage does not add credits.