Metrics
This guide helps you define metrics, send events, and query values. Metrics turn events into numbers that power usage-based pricing and entitlements.
Types:
- simple: built-in aggregations over a single event name
- indexed: SELECT/CTE SQL over
filtered_events(safer, faster) - complex: advanced SQL (still SELECT-only)
1) Send events from your backend
import { sendEvent } from "@getlumen/server";
await sendEvent({
name: "api-calls",
value: 1,
userId: "user_ext_456"
});2) Define metrics
Simple metric:
curl -X POST "https://api.getlumen.dev/v1/metrics" \
-H "Authorization: Bearer $LUMEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "API Calls",
"description": "Total number of API calls",
"queryType": "simple",
"aggregationType": "COUNT",
"eventName": "api-calls",
"valueType": "NUMERIC"
}'SQL metric (indexed):
curl -X POST "https://api.getlumen.dev/v1/metrics" \
-H "Authorization: Bearer $LUMEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Monthly Active Users",
"queryType": "indexed",
"sqlDefinition": "WITH logins AS (SELECT * FROM filtered_events WHERE event_name = 'user-login') SELECT COUNT(DISTINCT event_string) AS value FROM logins"
}'Tips:
- SQL must be SELECT-only and reference
filtered_events(CTEs allowed). - Prefer simple metrics when possible for performance and simplicity.
3) Query a metric value
curl -X GET "https://api.getlumen.dev/v1/metrics/metric_123/value?customerId=cust_123" \
-H "Authorization: Bearer $LUMEN_API_KEY"Notes:
- If you omit timeframe, the system returns the value across all available events.
- For more advanced timeframe queries, pass a timeframe object (ABSOLUTE/RELATIVE/ALL) as supported by the API.
4) Use metrics for billing and entitlements
- Usage components in pricing reference a metric to compute billable quantity.
- Entitlement checks for numeric features may return the current usage to compare against credits.