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

> Track how much each customer uses your product, and show it on records and dashboards.

Usage tracking measures how much each customer uses your product: for usage-based billing, adoption reporting, or health signals. You define a **usage module** that binds a *product* object to a *customer* object, record **usage events** between their records, and surface the totals with usage blocks anywhere in Custral.

## How it works

<CardGroup cols={3}>
  <Card title="Usage module" icon="diagram-project">
    A named binding between a product [object](/data/objects/overview) and a customer object. The two sides every event connects.
  </Card>

  <Card title="Usage events" icon="bolt">
    Each event ties a product record to a customer record with a quantity, e.g. "Customer A used 40 of Product X."
  </Card>

  <Card title="Usage blocks" icon="chart-mixed">
    Blocks that read a module and display its events or a rolled-up total, on record pages or dashboards.
  </Card>
</CardGroup>

## Set it up

<Steps>
  <Step title="Create a usage module">
    Give it a name (e.g. "Subscription Usage") and pick the **product** object and the **customer** object whose records the events connect.
  </Step>

  <Step title="Send usage events">
    Record events against the module. Each carries a product, a customer, and a quantity. Send them from your own systems to the usage ingest endpoint (see the [API reference](/dev/api-reference/overview)). If you'd rather not send Custral record IDs, point the module at an **identifier property** so your own product/customer keys resolve to the right records.
  </Step>

  <Step title="Show usage in the app">
    Add a usage block to a record page or a dashboard and point it at the module.
  </Step>
</Steps>

## The usage blocks

<CardGroup cols={2}>
  <Card title="Usage Event Log" icon="table-list">
    A paginated log of a module's events. Placed on a record page, it auto-scopes to that record. Its role decides which events show.
  </Card>

  <Card title="Usage Stat" icon="chart-mixed">
    A single aggregated metric for a module (**Count** of events or **Sum** of their quantities) scoped the same way on a record page.
  </Card>
</CardGroup>

**Roles.** A record is either the **product** or the **customer** side of a module. When a usage block sits on a record page, it filters to that record's role automatically, so a customer's page shows *their* usage, and a product's page shows usage *of it*. Leave the role empty for a global, unscoped view.

## What usage can and can't drive

The figure is computed when a record is read, and it is also written to the
search index, so it works both where a record is rendered and where a set of
records is queried.

| Works today                                                                        | Not yet                            |
| ---------------------------------------------------------------------------------- | ---------------------------------- |
| The total on a record page and as a grid column                                    | A workflow firing when usage drops |
| Filtering and sorting a view by a usage property                                   |                                    |
| A [grade](/data/properties/complex/grade) scoring on it, for health or churn risk  |                                    |
| Usage Stat and Usage Event Log blocks, on records and dashboards                   |                                    |
| The [Analytics](/blocks/embedded/object/analytics) block, charted over time        |                                    |
| A [formula](/data/properties/complex/formula) on the same object reading the value |                                    |

<Note>
  The indexed figure is a **snapshot**. It is 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.
</Note>

To compare accounts, sort a view by the usage column or by a grade that reads
it. A Usage Stat or a report on a dashboard still answers the aggregate
question, "how much did everyone use this month".

## Troubleshooting

**A usage block is empty.**
Either no events have been recorded for that module yet, the block points at the wrong module, or you're on a record whose object isn't the module's product or customer type (so nothing scopes to it).

**Events aren't landing on the right records.**
If you send your own keys instead of Custral record IDs, the module needs an **identifier property** set for that side. The ingest endpoint matches incoming keys against that property's value.

**A customer's page shows product-wide numbers.**
The block's role is empty (global). Set the block's **Record Role** so it scopes to the open record.

## Related

* [Objects & records](/data/objects/overview): the product and customer types a module binds.
* [Reporting overview](/bi/reporting/overview) · [Stat card](/bi/reporting/stat-card): other ways to surface metrics.
* [API reference](/dev/api-reference/overview): send usage events from your systems.


## Related topics

- [Browser SDK](/dev/sdks/browser.md)
- [Usage Stat](/blocks/embedded/usage/usage-stat.md)
- [Usage Event Log](/blocks/embedded/usage/usage-table.md)
- [Change Log](/product/updates.md)
- [TypeScript SDK](/dev/sdks/typescript.md)