> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Stat

> One aggregated usage number for a usage module.

## Overview

Usage Stat renders a single large number for a [usage module](/bi/reporting/usage): 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`.

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

## 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](/blocks/embedded/usage/usage-table): the individual events behind this number.
* [Usage tracking](/bi/reporting/usage): modules, events, and the ingest endpoint.
* [Usage property](/data/properties/complex/usage): the same aggregation as a property on the record.


## Related topics

- [Usage tracking](/bi/reporting/usage.md)
- [Usage Event Log](/blocks/embedded/usage/usage-table.md)
- [Analytics](/blocks/embedded/object/analytics.md)
- [Blocks](/blocks/overview.md)
- [Usage](/data/properties/complex/usage.md)