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

# Custom usage tracking

> Display custom usage metrics on Hyperline customer pages using aggregator visibility, default intervals, displayed values, and threshold alerts.

Custom usage tracking lets you show selected usage metrics directly on customer pages. It uses Hyperline aggregators, but focuses on customer visibility and monitoring rather than only billing.

Use it for metrics your team wants to watch at the account level, such as monthly active users, API calls, storage growth, seats provisioned, data processed, feature adoption, or plan-limit consumption.

## How it works

1. You send usage events to Hyperline or load them through a connector.
2. An [aggregator](../usage/aggregators) turns those events into a metric.
3. The aggregator's **Visibility** setting controls which customers can see that metric.
4. Visible metrics appear on the customer overview and in the customer **Usage** tab.
5. Thresholds can alert your team when a customer's value crosses a configured limit.

<Note>
  Custom usage tracking uses the same aggregator system as usage-based billing. If you need to create the underlying usage events first, start with [Send usage data](../usage/send-usage-data) or [Usage data with connectors](../usage/usage-data-with-connectors).
</Note>

## Configure a customer-visible usage metric

1. Go to **Usage > Aggregators**.
2. Create a new aggregator or open an existing one.
3. Configure the metric:
   * **Name**
   * **Event type**
   * **Operation**: **Count**, **Sum**, or **SQL formula**
   * **Unit name**
   * Optional filters
4. In **Visibility**, choose where the metric should appear:
   * **All customers**
   * **Specific segments and customers**
   * **No customers**
5. If the metric is visible to customers, set a default aggregation interval.
6. Choose the **Displayed value**:
   * **Total**: shows the total over the selected period.
   * **Last complete period**: shows the value from the last fully completed aggregation interval.
7. Add thresholds if you want to trigger alerts.
8. Click **Save changes**.

## Visibility options

| Visibility                          | Use when                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| **All customers**                   | The metric applies broadly, such as API calls for every account                     |
| **Specific segments and customers** | The metric is only relevant for a cohort or handpicked accounts                     |
| **No customers**                    | The aggregator is only used for billing, internal calculations, or another workflow |

When using **Specific segments and customers**, add one or more segment or customer conditions. The metric appears only for customers that match the configured visibility conditions.

## Where usage appears

Customer-visible aggregators appear in two places:

* **Customer overview**: top usage metric cards summarize the most relevant customer-visible metrics.
* **Usage tab**: the full list of visible usage cards includes charts, filters, thresholds, and event drill-downs.

For the full customer usage workflow, see [Customer usage](../usage/customer-usage).

In the **Usage** tab, you can change the period and grouping:

| Grouping    | Best for                          |
| ----------- | --------------------------------- |
| **Monthly** | Long-term customer trends         |
| **Daily**   | Weekly or monthly activity review |
| **Hourly**  | Intraday monitoring               |

Click **Explore** on a usage card to inspect the underlying events for that customer and metric.

## Use cases

| Use case             | Metric examples                                                      | What to watch for                                                 |
| -------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Upsell opportunity   | Seats provisioned, API calls, storage used, projects created         | Customers approaching limits or growing steadily                  |
| Add-on adoption      | Premium feature events, advanced workflow usage, extra modules used  | Customers getting value from features that map to paid add-ons    |
| Onboarding progress  | First import, first integration sync, active users, key setup events | Customers that have not reached expected milestones               |
| Engagement risk      | Active users, weekly activity, successful syncs, feature usage       | Declining activity or no usage after purchase                     |
| Usage overage review | Events above included allowance, credits consumed, peak usage        | Customers likely to exceed contracted usage                       |
| Capacity planning    | Data processed, records stored, transactions created                 | Customers whose usage may require a plan or infrastructure review |

## Thresholds

Thresholds let you alert on customer-level usage changes. A threshold can trigger when a value is greater than or equal to a limit, or less than or equal to a limit.

Thresholds are useful for:

* Usage spikes that may indicate overages
* Usage drops that may indicate churn risk
* Low adoption after onboarding
* Customers approaching contractual limits
* Customers reaching usage levels that may justify an upsell or add-on discussion

<Card title="Example 💡">
  You track monthly active users with an aggregator visible to all customers.
  You set the displayed value to **Last complete period** and add a threshold
  for fewer than `20` active users. When a customer's active user count drops
  below that limit, your team can review the account before renewal.
</Card>

<Card title="Example 💡">
  You track storage usage in GB and set a threshold at `800`. When the
  threshold is crossed, the customer owner can review whether the account is
  ready for a higher tier or an additional storage package.
</Card>

## Related

* [Aggregators](../usage/aggregators)
* [Customer usage](../usage/customer-usage)
* [Explore usage events and consumption](../usage/explore-usage-consumption)
* [Customer monitoring agent](./customer-monitoring-agent)