event_name and applies an aggregation function to produce a usage total that Borga uses when generating invoices.
Aggregate types
Create a meter
POST /v1/meters
Creates a new meter. Once created, the meter begins aggregating events that match its event_name.
Request parameters
string
required
Display name for the meter. Maximum 200 characters. Shown in the dashboard.
string
required
The name of the usage events this meter aggregates. Must match the
event_name field on ingested events exactly. Maximum 200 characters.string
required
The aggregation function to apply. One of
count, sum, max, min, avg, unique.string
The key in the event
metadata whose value is aggregated. Required for all aggregate_type values except count.object
An optional filter object. Only events whose
metadata matches all key-value pairs in this object are included in the aggregation.string
Human-readable label for the unit of measurement (e.g.
"API calls", "GB"). Displayed on invoices. Maximum 100 characters.number
Multiply the aggregated value by this number before billing. Minimum value is
1. Useful for converting raw event values to billing units (e.g. bytes to gigabytes).Response fields
string
required
Unique identifier for the meter (e.g.
mtr_xxx).string
required
Display name of the meter.
string
required
The event name this meter listens for.
string
required
The aggregation function applied to matching events.
string
The metadata key being aggregated.
null for count meters.string
Human-readable unit label shown on invoices.
number
Multiplier applied to the aggregated value before billing.
boolean
required
Whether this meter has been archived. Archived meters no longer aggregate new events.
List meters
GET /v1/meters
Returns a paginated list of meters.
Query parameters
string
Cursor for pagination. Pass the
id of the last meter from the previous page to retrieve the next page.number
Maximum number of meters to return per page.
boolean
When
true, include archived meters in the results. Defaults to false.Retrieve a meter
GET /v1/meters/{id}
Retrieves the details of an existing meter.
Path parameters
string
required
The ID of the meter to retrieve.
Archive a meter
DELETE /v1/meters/{id}
Archives a meter. Archived meters no longer aggregate new events and will not generate billable usage. The meter’s historical data is preserved and still accessible.
Path parameters
string
required
The ID of the meter to archive.
Get meter quantities
GET /v1/meters/{id}/quantities
Returns the aggregated usage total for a specific customer and time range.
Path parameters
string
required
The ID of the meter to query.
Query parameters
string
required
ID of the customer whose usage to retrieve.
string
required
Start of the time range to aggregate, as an ISO 8601 timestamp (e.g.
2026-04-01T00:00:00Z).string
required
End of the time range to aggregate, as an ISO 8601 timestamp (e.g.
2026-04-30T23:59:59Z).Response fields
string
required
ID of the meter.
string
required
ID of the customer.
string
required
Start of the queried period as an ISO 8601 timestamp.
string
required
End of the queried period as an ISO 8601 timestamp.
number
required
The aggregated usage value for the customer over the requested period, after applying
unit_multiplier.