Telemetry
Revenue and billing SQL recipe

Calculate Usage Quota Burn by Account

Measure billable units against each account's included monthly quota and rank accounts approaching an overage.

Beginnerusage_meter_eventsReviewed 2026-07-28Tested with Apache DataFusion 45.2.0

Reviewed by the Telemetry product team on . SQL compatibility, event contract, synthetic output, and operational caveats. Editorial ownership

Question answered

Which accounts are consuming their included usage fastest this month?

Usage-based billing needs a stable unit, an idempotent meter event, and the quota that applied when the usage occurred. This query makes quota consumption visible without treating raw event count as billable usage.

Event contract

Fields the query expects

FieldTypeWhy it exists
timestamp_utcTimestampWhen the billable activity completed in UTC.
meter_event_idUtf8Idempotency key for one logical usage record.
account_idUtf8Stable billing-account identifier.
planUtf8Plan that owned the quota when usage occurred.
billable_unitsFloat64Normalized units added by this event.
included_unitsFloat64Monthly included quota for the account and plan.
DataFusion SQL

Copy the query

sql
WITH deduplicated_usage AS (
  SELECT
    meter_event_id,
    account_id,
    plan,
    MAX(billable_units) AS billable_units,
    MAX(included_units) AS included_units
  FROM usage_meter_events
  WHERE timestamp_utc >= date_trunc('month', now())
  GROUP BY meter_event_id, account_id, plan
)
SELECT
  account_id,
  plan,
  COUNT(*) AS meter_events,
  SUM(billable_units) AS used_units,
  MAX(included_units) AS included_units,
  100.0 * SUM(billable_units)
    / NULLIF(MAX(included_units), 0) AS quota_used_pct,
  SUM(billable_units) - MAX(included_units) AS overage_units
FROM deduplicated_usage
GROUP BY account_id, plan
ORDER BY quota_used_pct DESC;

This read-only query is planned and executed against an empty typed table with Apache DataFusion 45.2.0. The deterministic sample output is synthetic and reviewed separately; validate field types, thresholds, and business definitions against your own data. Read the testing methodology.

Query result

Monthly quota used by account

Harbor has crossed its included quota, while Lumen is close enough to need a forecast or customer notification.

account_idplanmeter_eventsused_unitsincluded_unitsquota_used_pctoverage_units
account_harborgrowth18,4201,126,0001,000,000112.6126,000
account_lumengrowth12,880842,0001,000,00084.2-158,000
account_northstarter3,610168,000250,00067.2-82,000

Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.

Monthly quota used by account: static chart of synthetic quota_used_pct values from the Calculate Usage Quota Burn by Account example result
Indexable SVG of the deterministic example output. Download it for an article, runbook, or design review with attribution.

Reproduce the example

Download the public fixture

The JSON bundle includes the typed event contract, illustrative input rows, exact SQL, expected output, review notes, and engine version. The CSV contains the displayed result.

How the SQL works

  1. 1The first CTE groups by meter-event ID so an at-least-once delivery cannot bill the same logical usage twice.
  2. 2Billable units are summed independently from event count because one request can represent many or fractional units.
  3. 3Quota percentage and overage preserve the plan-specific denominator needed for account ranking and billing review.

Edge cases to decide

  • Plan changes need an explicit proration policy; a single monthly maximum is illustrative when quotas can change mid-period.
  • Corrections and negative usage require an append-only adjustment contract rather than silently mutating prior events.
  • Reconcile the aggregate with the billing provider before an invoice becomes final.

Recommended dashboard

  • Bars: quota_used_pct by account
  • Table: used, included, and overage units
  • Trend: daily billable units for accounts above 75%

Alert guidance

Notify account owners at documented quota thresholds and page only when meter delivery or reconciliation is failing.

Read alert setup

Put the recipe to work

Related instrumentation and guides

Continue the analysis

Run it on real events

Create a table, adapt the fields, and save the result

Start free, send structured events, and use the query result as a chart, shared dashboard widget, or alert input.

Get an API key