Usage metering

meter records what each tenant uses, idempotently and without slowing a request, so you can show a usage page, enforce a plan limit or bill by usage.

meter:
  driver: db
  metrics:
    api_calls: { unit: call, aggregate: sum }
    active_users: { unit: person, aggregate: unique, of: user }
  export:
    to: pay
    every: 1h
    metrics: { api_calls: { meter: api_calls } }

import { meter } from "mainsdk";

// counted once even if this step is retried
meter.record("audio_minutes", 2.5, { feature: "speech" });

const month = await meter.usage({ metric: "audio_minutes", window: "month" });

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { meter } from "mainsdk";

describe("usage", () => {
  it("counts a retried record once", async () => {
    const app = createTestApp({ main: "./main.yaml" });   // metrics: api_calls { aggregate: sum }
    await app.asTenant({ id: "tnt_a" }, async () => {
      meter.record("api_calls", 1, { idempotencyKey: "req-1" });
      meter.record("api_calls", 1, { idempotencyKey: "req-1" });
      await meter.flush();
      assert.equal((await meter.usage({ metric: "api_calls", window: "day" })).value, 1);
    });
  });
});

meter:
  driver: db

Quick start

meter:
  driver: local
  metrics:
    api_calls: { unit: call, aggregate: sum }

import { meter } from "mainsdk";

// call this once the request has succeeded; it returns { id, queued: true } at once
meter.record("api_calls", 1, { feature: "export" });

const usage = await meter.usage({ metric: "api_calls", window: "day" });
console.log(usage.value, usage.unit);   // { metric, value, unit, from, to, stale }

Configuration

meter:
  driver: db                       # local | db | redis; default: the runtime store's driver
  redis:                           # redis driver: one store per region
    eu: { url: secret:REDIS_EU_URL }
  metrics:
    api_calls:     { unit: call, aggregate: sum }
    storage_gb:    { unit: GB, aggregate: max }
    active_users:  { unit: person, aggregate: unique, of: user }
  keep: 400d                       # raw records; at least 35d
  flush: 1s                        # how often buffered records are written
  buffer: 10000                    # records held in memory while the store is down
  export:
    to: pay
    every: 1h
    late: 1h
    metrics:
      api_calls: { meter: api_calls }    # the provider's meter name

A metric you have not declared throws MAIN-METER-0001. Every call runs inside a tenant when tenancy is on.

What you get

• meter.record() returns at once and never throws because the store is down. A retried step, job or webhook records once.
• Usage by hour, day, month or range, split by feature, API key or user, in the tenant's region.
• Closed hours go to your billing provider through pay, with a total per tenant, metric and hour. A person's id in usage is pseudonymised when they are erased.
• Reach for it when your pricing has an included allowance and a price per unit beyond it, such as API calls, audio minutes or storage. It runs in your app on your own store and is free.

Reference

Examples

Meter AI requests per tenant

import { ai, meter } from "mainsdk";

export async function summarise(text: string, user: { id: string }) {
  const summary = await ai.generate({
    model: "anthropic/claude-sonnet",
    prompt: `Summarise: ${text}`,
    feature: "summary",
    user,
  });
  meter.record("ai_summaries", 1, { feature: "summary", user: user.id });
  return summary;
}

Declare ai_summaries under meter.metrics first.

Read usage split by feature

import { meter } from "mainsdk";

const usage = await meter.usage({ metric: "api_calls", window: "month", groupBy: ["feature"] });
for (const g of usage.groups ?? []) console.log(g.key.feature, g.value);

window is "hour", "day", "month" (UTC calendar windows) or { from, to } on whole hours, at most 13 months. Another tenant's usage needs tenant.system().

Count once when a step retries

Pass your own idempotencyKey when you have a natural one. Inside a workflow step, job or inbound webhook, the key defaults from that context. Outside any of them, with no key, nothing is deduplicated.

import { meter } from "mainsdk";

export function countMinutes(jobId: string, minutes: number) {
  meter.record("audio_minutes", minutes, { idempotencyKey: `transcribe:${jobId}` });
}

Duplicates are dropped when the batch is written (every flush), so a total read in the same second can briefly count a repeat.

Send usage to your billing provider

With meter.export, a scheduled job sends each tenant's total for every closed hour to the pay driver, with the identifier <tenant>:<metric>:<hour> so a retry counts once. Only totals leave the region: no user ids, API key ids or features.

import { pay } from "mainsdk";

// the same call the export job makes; the identifier makes a retry count once
await pay.reportUsage({
  customer: "cus_123",           // the provider's customer id
  meter: "api_calls",            // the provider's meter name
  value: 1200,
  at: Date.UTC(2026, 9, 27, 10),
  identifier: "tnt_acme:api_calls:2026-10-27T10",
});

Errors and checks

mainsdk check reports MAIN-METER-0001 for a literal metric name in code that is not declared, and MAIN-METER-0006 for local with --env prod. See check codes.

Swapping drivers

meter:
  driver: redis   # was db
  redis:
    eu: { url: secret:REDIS_EU_URL }

Your meter.record() calls stay the same. Past usage lives in the old store, so moving drivers is a data migration, not a one-line switch. Billing customers and past invoices live in your provider. See Swap a driver.

Testing

createTestApp puts meter on its in-memory driver with a fake clock. Every call runs inside a tenant, so wrap it in app.asTenant(). meter.flush() writes the buffer, so a total read after it is exact.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { meter } from "mainsdk";

describe("usage", () => {
  it("counts a retried record once", async () => {
    const app = createTestApp({ main: "./main.yaml" });   // metrics: api_calls { aggregate: sum }
    await app.asTenant({ id: "tnt_a" }, async () => {
      meter.record("api_calls", 1, { idempotencyKey: "req-1" });
      meter.record("api_calls", 1, { idempotencyKey: "req-1" });
      await meter.flush();
      assert.equal((await meter.usage({ metric: "api_calls", window: "day" })).value, 1);
    });
  });
});

Security and privacy

• The user dimension is personal data. When a person is erased, it is replaced in raw records by a keyed hash, so totals and unique counts stay right.
• Records stay in the tenant's region, and a record is never written to another region.
• meter is for your app's billing. It is separate from how MainSDK Cloud counts its own usage; see Free in the app, paid in the Cloud.

FAQ

Does meter charge the customer? No. It records usage; your billing provider prices and charges it, through pay.

How is this different from analytics? meter holds exact, idempotent billing facts. Analytics events are product signals and are approximate.

Can a plan limit read the meter? Yes. A limit whose source is meter:<metric> in entitlements reads meter.usage.

Next

• Limits, metering and entitlements
• Payments
• Rate limits and quotas