# Meters

> Turn usage events into a billable quantity per customer and period.

Source: https://docs.borga.is/api/meters

See [Usage-based billing](/billing/usage-based) for how meters, prices and events fit together.

**The meter object**

- `id` (string): Prefixed `mtr_`.
- `object` (string): `meter`
- `name` (string): <Param name="event_name" type="string">Matched against `event_name` on usage events.
- `aggregate` (object): `type` (`count`, `sum`, `max`, `min`, `avg`, `unique`) and `property`.
- `filter` (object | null): Metadata conditions events must match.
- `unit_label` (string | null): - `unit_multiplier` (integer | null) - `archived_at` (timestamp | null) - `created_at` (timestamp) - `updated_at` (timestamp) ## Create a meter `POST /v1/meters` **Body** <Param name="name" type="string" required>Up to 200 characters.
- `event_name` (string, required): Up to 200 characters.
- `aggregate_type` (enum, required): `count`, `sum`, `max`, `min`, `avg` or `unique`.
- `aggregate_property` (string): Metadata path such as `metadata.total_tokens`. Required unless `aggregate_type` is `count`.
- `filter` (object): Only events whose metadata matches count, e.g. `{ "metadata.tier": "pro" }`.
- `unit_label` (string): Shown on invoices, e.g. `tokens`.
- `unit_multiplier` (integer): Divide the aggregate by this before pricing.

```ts Node.js
// Count API requests
const requests = await borga.meters.create({
  name: "API requests",
  event_name: "api_request",
  aggregate_type: "count",
  unit_label: "requests",
});

// Sum tokens, priced per million
const tokens = await borga.meters.create({
  name: "LLM tokens",
  event_name: "llm_completion",
  aggregate_type: "sum",
  aggregate_property: "metadata.total_tokens",
  unit_label: "tokens",
  unit_multiplier: 1_000_000,
});
```

Errors: [`missing_aggregate_property`](/errors/missing_aggregate_property).

## Retrieve a meter

`GET /v1/meters/:id`

## List meters

`GET /v1/meters`

**Query parameters**

- `archived` (boolean): `true` includes archived meters.
- `limit` (integer, default 25): - `starting_after` (string) ## Archive a meter `DELETE /v1/meters/:id` Archived meters stop accepting events but keep their history and remain readable. ## Meter quantity for a period `GET /v1/meters/:id/quantities` Aggregates one customer's events over a period. **Query parameters** - `customer` (string) <Param name="period_start" type="timestamp">Defaults to the customer's current billing period.
- `period_end` (timestamp)

```json title="Response"
{
  "meter": "mtr_1Zx3Cv5Bn7Mq9We1Rt3Yu5Io",
  "customer": "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
  "period_start": "2026-09-01T00:00:00.000Z",
  "period_end": "2026-10-01T00:00:00.000Z",
  "quantity": 14250,
  "unit_label": "requests"
}
```

## Customer meter balance

`GET /v1/customer-meters/:customerId/:meterId`

The live state of a customer's meter in the current period, including included units and overage.

```ts Node.js
const balance = await borga.meters.balance(
  "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
  "mtr_1Zx3Cv5Bn7Mq9We1Rt3Yu5Io",
);

console.log(balance.consumed_units, "of", balance.included_units);
console.log("overage:", balance.overage_units);
```

```json title="Response"
{
  "customer": "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
  "meter": "mtr_1Zx3Cv5Bn7Mq9We1Rt3Yu5Io",
  "period_start": "2026-09-01T00:00:00.000Z",
  "period_end": "2026-10-01T00:00:00.000Z",
  "consumed_units": 7420,
  "included_units": 10000,
  "balance": 2580,
  "overage_units": 0
}
```

## Customer billing state

`GET /v1/customer-state/:customerId`

Everything needed for a customer-facing billing page in one call: active, trialing and past-due subscriptions with their items, and every meter balance.

```json title="Response"
{
  "customer": "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
  "subscriptions": [
    {
      "id": "sub_9Qw1Er3Ty5Ui7Op9As1Df3Gh",
      "status": "active",
      "current_period_start": "2026-09-01T00:00:00.000Z",
      "current_period_end": "2026-10-01T00:00:00.000Z",
      "cancel_at_period_end": false,
      "items": [{ "id": "si_…", "price": "price_…", "quantity": 3 }]
    }
  ],
  "meters": [
    {
      "meter": "mtr_1Zx3Cv5Bn7Mq9We1Rt3Yu5Io",
      "name": "API requests",
      "unit_label": "requests",
      "consumed_units": 7420,
      "included_units": 10000,
      "balance": 2580,
      "overage_units": 0,
      "period_start": "2026-09-01T00:00:00.000Z",
      "period_end": "2026-10-01T00:00:00.000Z"
    }
  ]
}
```