> ## 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

> Roll product-usage events up onto a record.

## Overview

A Usage property shows how much a customer actually used something, by
aggregating the events you've sent to a
[usage module](/bi/reporting/usage). API calls this month, seats consumed,
messages sent. Pick it from **Complex** in the property type list.

Like a rollup, it's computed at read time and **read-only**.

## Configuration

| Setting     | What it does                                                                    |
| ----------- | ------------------------------------------------------------------------------- |
| Module      | Which usage module supplies the events.                                         |
| Aggregation | `Count` of events, or `Sum` of each event's quantity.                           |
| Role        | Whether this record is matched as the module's **customer** or its **product**. |
| Window      | A rolling window in days, counted back from now. Leave empty for all time.      |

<Note>
  The window is **rolling**, not a fixed date range, "last 30 days" always means
  the 30 days ending now, so the value can't go stale.
</Note>

## What it stores

Nothing on the record. It's computed from the module's events each time the
record is read.

## Filtering, sorting and grading on it

The number is written to the search index as an ordinary number, so a Usage
property behaves like any other numeric column:

* **Filter a view on it**, "API calls this month is under 5".
* **Sort by it**, and use it in a table's footer calculations.
* **Score a [grade](/data/properties/complex/grade) on it.** Point a rubric's
  field criterion at the Usage property, the same way you would at any other
  field, and use it to drive onboarding health or churn risk.
* **Read it from a [formula](/data/properties/complex/formula)** on the same
  object.

<Note>
  The indexed figure is a **snapshot**, refreshed overnight and whenever the
  record is next saved, so a view can be up to a day behind a burst of events. A
  **grade** is not: it aggregates the events live every time it recomputes, so the
  score is exact at the moment it was calculated.
</Note>

<Warning>
  No workflow can trigger on a Usage property changing. Nothing sends an event
  when the number moves, so "flip this account to At Risk when usage drops" isn't
  something you can build today. A grade on the same object re-scores overnight,
  which gives you a column to sort and filter by instead.
</Warning>

## Examples

* **API calls (30d)** on an Account: count, customer role, 30-day window.
* **Seats used** on a Subscription, sum of quantity, all time.

## See also

* [Usage reporting](/bi/reporting/usage): creating modules and sending events.
* [Rollup](/data/properties/complex/rollup): aggregate related records instead of events.


## Related topics

- [Usage Stat](/blocks/embedded/usage/usage-stat.md)
- [Usage tracking](/bi/reporting/usage.md)
- [The Usage module object](/dev/api-reference/usage-modules.md)
- [Retrieve a usage module](/api-reference/usage-modules/retrieve-a-usage-module.md)
- [List usage events](/api-reference/usage-modules/list-usage-events.md)