> ## 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.

# Meters API — track usage for metered billing

> Create meters that define how usage events are aggregated for metered subscription pricing. Query per-customer usage totals for any time range.

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**

| Type     | Description                                                                              |
| -------- | ---------------------------------------------------------------------------------------- |
| `count`  | Counts the number of matching events. No `aggregate_property` needed.                    |
| `sum`    | Sums the numeric value of `aggregate_property` across all matching events.               |
| `max`    | Returns the maximum value of `aggregate_property` across all matching events.            |
| `min`    | Returns the minimum value of `aggregate_property` across all matching events.            |
| `avg`    | Returns the average value of `aggregate_property` across all matching events.            |
| `unique` | Counts 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

<ParamField body="name" type="string" required>
  Display name for the meter. Maximum 200 characters. Shown in the dashboard.
</ParamField>

<ParamField body="event_name" type="string" required>
  The name of the usage events this meter aggregates. Must match the `event_name` field on ingested events exactly. Maximum 200 characters.
</ParamField>

<ParamField body="aggregate_type" type="string" required>
  The aggregation function to apply. One of `count`, `sum`, `max`, `min`, `avg`, `unique`.
</ParamField>

<ParamField body="aggregate_property" type="string">
  The key in the event `metadata` whose value is aggregated. Required for all `aggregate_type` values except `count`.
</ParamField>

<ParamField body="filter" type="object">
  An optional filter object. Only events whose `metadata` matches all key-value pairs in this object are included in the aggregation.
</ParamField>

<ParamField body="unit_label" type="string">
  Human-readable label for the unit of measurement (e.g. `"API calls"`, `"GB"`). Displayed on invoices. Maximum 100 characters.
</ParamField>

<ParamField body="unit_multiplier" type="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).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique identifier for the meter (e.g. `mtr_xxx`).
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name of the meter.
</ResponseField>

<ResponseField name="event_name" type="string" required>
  The event name this meter listens for.
</ResponseField>

<ResponseField name="aggregate_type" type="string" required>
  The aggregation function applied to matching events.
</ResponseField>

<ResponseField name="aggregate_property" type="string">
  The metadata key being aggregated. `null` for `count` meters.
</ResponseField>

<ResponseField name="unit_label" type="string">
  Human-readable unit label shown on invoices.
</ResponseField>

<ResponseField name="unit_multiplier" type="number">
  Multiplier applied to the aggregated value before billing.
</ResponseField>

<ResponseField name="archived" type="boolean" required>
  Whether this meter has been archived. Archived meters no longer aggregate new events.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "mtr_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "name": "API calls",
    "event_name": "api.request",
    "aggregate_type": "count",
    "aggregate_property": null,
    "unit_label": "requests",
    "unit_multiplier": 1,
    "archived": false
  }
  ```
</ResponseExample>

***

## List meters

`GET /v1/meters`

Returns a paginated list of meters.

### Query parameters

<ParamField query="starting_after" type="string">
  Cursor for pagination. Pass the `id` of the last meter from the previous page to retrieve the next page.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of meters to return per page.
</ParamField>

<ParamField query="archived" type="boolean">
  When `true`, include archived meters in the results. Defaults to `false`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

***

## Retrieve a meter

`GET /v1/meters/{id}`

Retrieves the details of an existing meter.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the meter to retrieve.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/meters/mtr_01hx9z3k2mfq7nbvd4cw8ej5rt \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

***

## 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

<ParamField path="id" type="string" required>
  The ID of the meter to archive.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.borga.is/v1/meters/mtr_01hx9z3k2mfq7nbvd4cw8ej5rt \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

***

## Get meter quantities

`GET /v1/meters/{id}/quantities`

Returns the aggregated usage total for a specific customer and time range.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the meter to query.
</ParamField>

### Query parameters

<ParamField query="customer" type="string" required>
  ID of the customer whose usage to retrieve.
</ParamField>

<ParamField query="period_start" type="string" required>
  Start of the time range to aggregate, as an ISO 8601 timestamp (e.g. `2026-04-01T00:00:00Z`).
</ParamField>

<ParamField query="period_end" type="string" required>
  End of the time range to aggregate, as an ISO 8601 timestamp (e.g. `2026-04-30T23:59:59Z`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

### Response fields

<ResponseField name="meter" type="string" required>
  ID of the meter.
</ResponseField>

<ResponseField name="customer" type="string" required>
  ID of the customer.
</ResponseField>

<ResponseField name="period_start" type="string" required>
  Start of the queried period as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="period_end" type="string" required>
  End of the queried period as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="quantity" type="number" required>
  The aggregated usage value for the customer over the requested period, after applying `unit_multiplier`.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meter": "mtr_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "customer": "cus_abc123",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "quantity": 14823
  }
  ```
</ResponseExample>