> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monigo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Metering

> Accurately track usage across your product with Monigo's event ingestion API.

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

```typescript theme={null}
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:**

```bash theme={null}
POST /v1/events
```

**Batch (up to 1,000 events):**

```bash theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
GET /v1/customers/{id}/usage?metric=api_calls&from=2026-02-01&to=2026-02-28
```

Response:

```json theme={null}
{
  "metric": "api_calls",
  "total": 847293,
  "period": { "from": "2026-02-01", "to": "2026-02-28" }
}
```