Skip to main content
Metering is the foundation of Monigo. Every billable action in your product should produce a metering event that Monigo records, aggregates, and uses for billing.

​
The event model

type MeteringEvent = {
  customer_id: string;       // which customer
  event_name: string;        // what happened (maps to a metric)
  quantity: number;          // how much (default: 1)
  idempotency_key: string;   // unique per event for dedup
  timestamp?: string;        // ISO 8601, defaults to now
  properties?: Record<string, unknown>; // arbitrary metadata
};

​
Sending events

The ingestion endpoint accepts single events or batches. Single event: 
POST /v1/events
Batch (up to 1,000 events): 
POST /v1/events/batch
Content-Type: application/json

{
  "events": [ ... ]
}

​
Idempotency

The idempotency_key is the most important field. Monigo will deduplicate any two events with the same key, making retries safe. Use a stable, unique identifier for each event — typically a UUID generated at the time of the action: 
import { randomUUID } from 'crypto';

await monigo.events.ingest({
  customer_id: customerId,
  event_name: 'api_calls',
  quantity: 1,
  idempotency_key: randomUUID(),
});

​
Backdating events

You can send events with a past timestamp. This is useful for:
  • Recovering from an outage where events weren’t sent in real time
  • Importing historical data during onboarding
Events can be backdated up to 90 days. Events older than that are rejected.

​
Querying usage

View aggregated usage in the dashboard under Metrics, or query via API: 
GET /v1/customers/{id}/usage?metric=api_calls&from=2026-02-01&to=2026-02-28
Response: 
{
  "metric": "api_calls",
  "total": 847293,
  "period": { "from": "2026-02-01", "to": "2026-02-28" }
}