Events

Events connect what happens in your product to billing and entitlements. They are immutable records you emit after successful actions (not before), and Lumen deduplicates them using idempotencyKey for 24 hours.

Design your event model

Think about events as facts you’ll aggregate later:

• Name events for the action: api-call, file-upload, seat_added
• Include dimensions in properties you’ll filter by later: endpoint, region, status, plan
• Choose one primary value per event:
  • eventValue for numeric amounts (e.g., tokens, bytes)
  • eventString for identity-like values (e.g., userId for MAU)

Event shape (minimal):

{
  "eventName": "api-call",
  "customerId": "cus_123",        // or extCustomerId
  "eventValue": 1,                  // exactly one of eventValue or eventString
  "idempotencyKey": "evt_12345",  // reuse on retries
  "eventTimestamp": "2025-01-01T10:00:00Z",
  "properties": { "endpoint": "/v1/widgets", "status": 200 }
}

Constraints:

• Provide at least one of customerId or extCustomerId
• Provide exactly one of eventValue or eventString

Emitting events

• Single actions: send one event after success
• Bulk processing: batch up to 100 events per request

Examples (trimmed):

# Single
curl -X POST "$API_URL/v1/events" -H "Authorization: Bearer $LUMEN_SECRET_KEY" -H "Content-Type: application/json" -d '{
  "eventName": "api-call", "customerId":"cus_123", "eventValue":1, "idempotencyKey":"evt_12345"
}'

# Batch
curl -X POST "$API_URL/v1/events/batch" -H "Authorization: Bearer $LUMEN_SECRET_KEY" -H "Content-Type: application/json" -d '{
  "events": [
    { "eventName":"api-call", "customerId":"cus_1", "eventValue":1 },
    { "eventName":"api-call", "customerId":"cus_2", "eventValue":1 }
  ]
}'

Mapping events to metrics

• Count API requests → simple metric: COUNT of api-call
• Sum AI tokens → simple metric: SUM of eventValue on ai-token
• Monthly active users → SQL metric: COUNT(DISTINCT event_string) of user-login

Create the metric once, then reuse it across pricing and entitlement checks. See Metrics.

Debugging

• Explore recent events with list filters (name, customer, date)
• Discover shapes via helper endpoints: unique event names and known customer IDs
• If a metric reads zero, confirm the event names match exactly and the timeframe covers your data

Operational habits

• Naming: Use stable, lowercase slugs with hyphens: api-call, ai-token, user-login. Version event names when their meaning changes, e.g., api-call.v2.
• Idempotency: Generate and persist an idempotencyKey per action; retry with the same key. The Events API deduplicates for 24 hours.
• Timing: Emit events only after success (e.g., after a request completes or a job finishes), never before.
• Properties: Include dimensions in properties you may want to filter by later, such as region, plan, endpoint, or status. Keep them primitive (string/number/boolean) for fast indexing.

See also

• Model what you sell: Modeling Features
• Compute billing values: Metrics
• Control access: Entitlements
• Troubleshoot patterns: Troubleshooting & Patterns