Usage Stat - Custral Docs

Overview

Usage Stat renders a single large number for a usage module: either how many events it has recorded, or the total of their quantities. Placed on a record page it scopes to that record, so a customer’s page shows their own consumption.

Configuration

Setting	What it does
Usage Module	The usage module to aggregate. Required.
Aggregation	`Count` of events, or `Sum` of their quantities. Defaults to `Count`.
Record Role	On a record page, scope the number to that record’s role: `product` or `customer`. Leave empty for a global, unscoped total.

The caption under the number follows the aggregation: Total Events for Count, Total Quantity for Sum.

Record Role is what makes the block record-aware. With it empty, the same module-wide total shows on every record.

Use cases

Seats used on a Subscription record, Sum, customer role.
API calls this period on an Account, Count, customer role.
A module-wide total on a billing dashboard, with no role set.

Troubleshooting

Symptom	Likely cause	What to check
”No usage module configured”	The block has no module selected	Set Usage Module.
Shows `0`	No events recorded for the module yet, or none match the scoped record	Confirm events are landing, and that the open record is the module’s product or customer object.
Every record shows the same number	Record Role is empty, so the block is global	Set the role to `product` or `customer`.

See also

Usage Event Log: the individual events behind this number.
Usage tracking: modules, events, and the ingest endpoint.
Usage property: the same aggregation as a property on the record.