Skip to main content
Meters are the foundation of usage tracking in SolvaPay. A meter defines what to measure and how to aggregate usage data. Usage records are the raw data points recorded against those definitions and stored in the Usage timeseries collection. Every provider automatically gets a requests meter when created. This meter is the only meter in the system — it tracks all billable request activity and powers limit enforcement, usage billing, and analytics.

​
How Meters Work

  1. Each provider gets a requests meter automatically — no configuration needed
  2. Your application records usage via the SDK, NATS, or automatically through MCP tool calls
  3. Other systems consume the data — plans enforce limits, billing calculates costs, dashboards visualize trends

​
Meter Fields

FieldTypeDescription
referencestringAuto-generated unique identifier (mtr_XXXXXXXX)
namestringMachine-readable name, unique per provider (e.g. requests)
displayNamestringHuman-readable label shown in dashboards
descriptionstring?Optional description of what the meter tracks
aggregationenumHow usage records are aggregated: count or sum
unitstringLabel for the metric unit (e.g. requests)
statusenumactive or archived

​
The requests Meter

Every provider automatically receives a requests meter when their account is created:
NameAggregationUnitPurpose
requestscountrequestsTracks all billable request activity
This meter is auto-configured per provider and cannot be archived. It is seeded idempotently — creating a provider multiple times is safe.

​
Aggregation

The requests meter uses count aggregation, which counts each usage record as one unit. SolvaPay also supports sum aggregation for meters that accumulate numeric values (e.g. tokens consumed), though only the requests meter is currently in use.
AggregationBehavior
countEach usage record counts as 1
sumEach usage record contributes its value field to the total

​
How Meters Connect to Plans

Usage-based and hybrid plans specify measures: 'requests', which links them to the provider’s auto-assigned requests meter. This link enables:
  • Limit enforcement — the plan’s limit field sets a hard cap on the meter’s aggregated value per billing period
  • Free units — the plan’s freeUnits field defines how many units are included before billing starts
  • Usage billing — at end-of-period, the meter’s aggregated value determines the billable amount
See Plans and Billing for details.

​
Next Steps

  • Usage Records — recording and querying usage data
  • Plans — how plans reference meters for billing and limits
  • Billing — end-of-period usage billing