reportUsage()

Unlike consume(), reportUsage() never blocks on the limit - it always applies. Use it when the thing you’re gating was already allowed some other way (e.g. a background job re-syncing usage counts, or metering something after the fact rather than at the moment of use).

await kerne.reportUsage('storage_megabytes', {
  customer: userId,
  delta: 2560,
  operation: 'INCREMENT', // or 'SET' to replace the value outright
  idempotencyKey: syncJobId,
});

string

required

Required here (unlike consume()/check()) - there’s no self-fallback for this one, you always name a customer.

number

A whole number, defaults to 1. Meter in the smallest unit you bill (megabytes, not gigabytes) - a fractional delta is rejected, not rounded.

'INCREMENT' | 'SET'

Defaults to INCREMENT.

string

Same replay-safety as consume().

object

Arbitrary context stored alongside the usage event (e.g. request_id).

string

Same field as consume()’s dimension - routes the write to the right per-dimension counter on a plan that counts per machine, project or seat. The SDK param is dimension; it is sent on the wire as dimension_id. One difference from consume(): that one requires it on a dimensioned feature (it’s gating access), reportUsage() doesn’t (it never blocks) - omit it and the write lands on the feature’s shared counter instead of a specific dimension.

Many at once

reportUsageBatch() sends up to 100 events in one request instead of one call each - for a fleet or batch producer reporting several customers/features at a time.

const results = await kerne.reportUsageBatch(
  machines.map((m) => ({
    featureKey: 'machine_minutes',
    customer: m.ownerId,
    dimension: m.id,
    delta: m.minutes,
  })),
);

Each event still gets reportUsage()’s own transaction and idempotency handling. One bad event (unknown featureKey, transient error) fails on its own without discarding the rest - the result is an array of { index, status: 'ok' | 'error', usage?, error? }, so check status per entry rather than assuming all-or-nothing.

Server SDK

Frontend SDKs

reportUsage()

Many at once

​Many at once

Many at once