Core Concepts
Understanding these concepts will help you get the most out of Meterd.
Tenants
Every resource in Meterd belongs to a tenant. Tenants provide complete data isolation — one tenant can never access another tenant's data. Each tenant has its own meters, customers, events, API keys, and quotas.
Events
Events are the raw data that Meterd ingests. An event represents a single action or occurrence in your system:
{
"event_type": "api_request",
"customer_id": "01HQXYZ...",
"timestamp": "2024-01-15T10:30:00Z",
"properties": {
"endpoint": "/v1/users",
"method": "GET",
"bytes": 1024
},
"value": 1.0,
"idempotency_key": "req_abc123"
}| Field | Description |
|---|---|
event_type | Categorizes the event. Meters filter on this. |
customer_id | The customer's external ID (not the internal ULID). |
properties | Arbitrary key-value data. Used for filtering and grouping. |
value | Numeric value for sum/max/min aggregations. Defaults to 1.0. |
idempotency_key | Prevents duplicate processing on retries. |
Meters
Meters define how events are aggregated into usage metrics.
| Field | Description | Example |
|---|---|---|
slug | Unique identifier | api-requests |
event_type | Which events to aggregate | api_request |
aggregation | How to combine values | count, sum, max |
window_size | Time bucket size | minute, hour, day |
value_property | Property to aggregate (for sum/max/min) | properties.bytes |
group_by | Dimensions to break down by | ["region", "tier"] |
filters | Only include matching events | status = 200 |
Aggregation types
| Type | Description |
|---|---|
count | Number of events |
sum | Sum of value or a named property |
count_unique | Distinct values of a property |
max | Maximum value |
average | Mean value |
last | Most recent value |
percentile | Percentile value (e.g., p99). Requires a percentile parameter: { "type": "percentile", "percentile": 99 } |
Windows
Aggregation happens within time windows — fixed-size buckets that events fall into based on their timestamp. Window sizes: minute, hour, or day.
Events are aggregated within each window. Once a window closes, it is marked as final.
Customers
Customers represent the end users or accounts whose usage you're tracking. Each customer has an internal ID (auto-generated ULID), an external ID (your system's identifier), and optional name and metadata.
Features
Features are named capabilities with optional default quota limits (e.g., "API Calls", "Storage GB"). Features are bundled into plans with specific quota configurations.
Plans
Plans bundle features with per-feature quota limits, reset periods, and enforcement modes. Plans belong to an application.
Quotas
Quotas let you enforce usage limits in real time:
- Check — Ask "can this customer use X more units?" (low-latency, real-time)
- Reserve — Two-phase commit: reserve capacity, then commit or release
- Audit — Every quota decision is logged for debugging and compliance
Enforcement modes: hard_cap (reject over-limit), soft_cap (allow but flag for billing).
Override hierarchy: Customer-specific override > Plan-feature limit > Feature default.
Reservations
Reservations are two-phase quota holds. Reserve capacity upfront (valid for 5 minutes), then commit or release. Reservation states: reserved, committed, released, expired.
Webhooks
Subscribe to events like quota exceeded, usage threshold reached, or spike detection. Each delivery is signed with HMAC-SHA256 and includes retry logic with exponential backoff.