Understanding units vs total_aggregated_units in the current usage API response

Lago's current_usage API response contains three fields that look related but behave differently: units, total_aggregated_units, and units inside grouped_usage entries. For most aggregation types these values align, but they diverge for weighted-sum aggregations. Using the wrong field for pricing calculations or dashboards can produce incorrect totals.

How it works

For standard aggregation types (count, sum, max, unique count, and so on), the top-level units on a charge object equals the sum of units across all entries in the grouped_usage array, and also equals total_aggregated_units. All three are equivalent in these cases.

For weighted-sum aggregations, the fields diverge:

• Top-level units: the time-weighted result, which is what Lago uses for pricing. This is the authoritative figure.

• total_aggregated_units: the net sum of event values for the period, before time-weighting is applied. It can be higher or lower than units depending on the timing and sign of events. With purely additive usage it tends to be higher, but when events include decrements the net sum can fall below the time-weighted figure.

• units in grouped_usage entries: the weighted result per group. These do sum to the top-level units for weighted-sum.

Which field to use

Always use the top-level units field on a charge object as the authoritative usage total. It is what drives pricing across all aggregation types and stays consistent regardless of whether grouping or weighting is involved.

Do not sum units from grouped_usage entries manually. While that works for most types, it is redundant and could behave unexpectedly if grouping logic changes. Do not use total_aggregated_units as a pricing input for weighted-sum metrics.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.