Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.borga.is/llms.txt

Use this file to discover all available pages before exploring further.

A meter defines how raw usage events are aggregated into a billable quantity. Each meter listens for events with a given event_name and applies an aggregation function to produce a usage total that Borga uses when generating invoices. Aggregate types
TypeDescription
countCounts the number of matching events. No aggregate_property needed.
sumSums the numeric value of aggregate_property across all matching events.
maxReturns the maximum value of aggregate_property across all matching events.
minReturns the minimum value of aggregate_property across all matching events.
avgReturns the average value of aggregate_property across all matching events.
uniqueCounts the number of distinct values of aggregate_property across all matching events.

​
Create a meter

POST /v1/meters Creates a new meter. Once created, the meter begins aggregating events that match its event_name.

​
Request parameters

​
name
string
required
Display name for the meter. Maximum 200 characters. Shown in the dashboard.
​
event_name
string
required
The name of the usage events this meter aggregates. Must match the event_name field on ingested events exactly. Maximum 200 characters.
​
aggregate_type
string
required
The aggregation function to apply. One of count, sum, max, min, avg, unique.
​
aggregate_property
string
The key in the event metadata whose value is aggregated. Required for all aggregate_type values except count.
​
filter
object
An optional filter object. Only events whose metadata matches all key-value pairs in this object are included in the aggregation.
​
unit_label
string
Human-readable label for the unit of measurement (e.g. "API calls", "GB"). Displayed on invoices. Maximum 100 characters.
​
unit_multiplier
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).
curl --request POST \
  --url https://api.borga.is/v1/meters \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "API calls",
    "event_name": "api.request",
    "aggregate_type": "count",
    "unit_label": "requests",
    "unit_multiplier": 1
  }'

​
Response fields

​
id
string
required
Unique identifier for the meter (e.g. mtr_xxx).
​
name
string
required
Display name of the meter.
​
event_name
string
required
The event name this meter listens for.
​
aggregate_type
string
required
The aggregation function applied to matching events.
​
aggregate_property
string
The metadata key being aggregated. null for count meters.
​
unit_label
string
Human-readable unit label shown on invoices.
​
unit_multiplier
number
Multiplier applied to the aggregated value before billing.
​
archived
boolean
required
Whether this meter has been archived. Archived meters no longer aggregate new events.
{
  "id": "mtr_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "name": "API calls",
  "event_name": "api.request",
  "aggregate_type": "count",
  "aggregate_property": null,
  "unit_label": "requests",
  "unit_multiplier": 1,
  "archived": false
}

​
List meters

GET /v1/meters Returns a paginated list of meters.

​
Query parameters

​
starting_after
string
Cursor for pagination. Pass the id of the last meter from the previous page to retrieve the next page.
​
limit
number
Maximum number of meters to return per page.
​
archived
boolean
When true, include archived meters in the results. Defaults to false.
curl --request GET \
  --url "https://api.borga.is/v1/meters?limit=20&archived=false" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Retrieve a meter

GET /v1/meters/{id} Retrieves the details of an existing meter.

​
Path parameters

​
id
string
required
The ID of the meter to retrieve.
curl --request GET \
  --url https://api.borga.is/v1/meters/mtr_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
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

​
id
string
required
The ID of the meter to archive.
curl --request DELETE \
  --url https://api.borga.is/v1/meters/mtr_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Get meter quantities

GET /v1/meters/{id}/quantities Returns the aggregated usage total for a specific customer and time range.

​
Path parameters

​
id
string
required
The ID of the meter to query.

​
Query parameters

​
customer
string
required
ID of the customer whose usage to retrieve.
​
period_start
string
required
Start of the time range to aggregate, as an ISO 8601 timestamp (e.g. 2026-04-01T00:00:00Z).
​
period_end
string
required
End of the time range to aggregate, as an ISO 8601 timestamp (e.g. 2026-04-30T23:59:59Z).
curl --request GET \
  --url "https://api.borga.is/v1/meters/mtr_01hx9z3k2mfq7nbvd4cw8ej5rt/quantities?customer=cus_abc123&period_start=2026-04-01T00%3A00%3A00Z&period_end=2026-04-30T23%3A59%3A59Z" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
meter
string
required
ID of the meter.
​
customer
string
required
ID of the customer.
​
period_start
string
required
Start of the queried period as an ISO 8601 timestamp.
​
period_end
string
required
End of the queried period as an ISO 8601 timestamp.
​
quantity
number
required
The aggregated usage value for the customer over the requested period, after applying unit_multiplier.
{
  "meter": "mtr_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "customer": "cus_abc123",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "quantity": 14823
}