Events API

The Events API lets your application record usage events that drive metered features, credit consumption, analytics dashboards, and real-time entitlement checks. It is the primary ingestion endpoint for all customer activity and is therefore a prerequisite for the Entitlements API documented in Entitlements API.

Overview

• Single Event Ingestion – POST /api/events • Batch Event Ingestion – POST /api/events/batch (up to 1000 events per request) • Historical Query – GET /api/events (filter by customer, event name, date range, …) • Back-fill – POST /trigger/events-backfill (internal tool for migrating data – merchant authenticated)

All requests are merchant-scoped and require the same authentication scheme used throughout the API.

Idempotency Events supply an optional idempotencyKey. The platform stores the key for 24 h to guarantee at-most-once ingestion. Duplicate keys are accepted with HTTP 202 and silently ignored.

Event Object

*One customer identifier is required, either customerId or extCustomerId.

Endpoints

Ingest Single Event

POST https://api.getlumen.dev/v1/events

{
  "eventName": "image-generation",
  "customerId": "cust_123",
  "eventValue": 1,
  "idempotencyKey": "evt_001" // optional
}

Successful ingestion returns:

{ "message": "Event accepted" }

202 Accepted is returned because the event is persisted asynchronously.

Errors

Ingest Batch of Events

POST https://api.getlumen.dev/v1/events/batch

{
  "events": [
    {
      "eventName": "api-call",
      "customerId": "cust_1",
      "eventValue": 1,
      "idempotencyKey": "call_001"
    },
    {
      "eventName": "api-call",
      "customerId": "cust_1",
      "eventValue": 1,
      "idempotencyKey": "call_002"
    }
  ]
}

The response summarises processed vs duplicate events:

{ "message": "Batch received. Processed 2 new events." }

Duplicates (events whose idempotencyKey already exists) are skipped and reported in the message string.

Query Events

Retrieve historical events for analytics or debugging.

GET https://api.getlumen.dev/v1/events?eventName=image-generation&customerId=cust_123&limit=100&offset=0&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z

Query Parameters

Example response:

{
  "data": [
    {
      "eventName": "image-generation",
      "idempotencyKey": "evt_001",
      "customerId": "cust_123",
      "extCustomerId": "user_123",
      "eventValue": 1,
      "properties": { "size": "1024x1024" },
      "eventTimestamp": "2024-01-15T12:34:56Z"
    }
  ],
  "pagination": { "limit": 100, "offset": 0, "hasMore": false }
}

Count Events

Get the total count of events matching the given filters.

GET https://api.getlumen.dev/v1/events/count?eventName=image-generation&customerId=cust_123&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z

Query Parameters

Same as Query Events.

Response

{ "totalCount": 42 }

Get Unique Event Names

Fetch the distinct set of event names for the merchant.

GET https://api.getlumen.dev/v1/events/unique-event-names

Response

{ "eventNames": ["api-call", "image-generation"] }

Get Unique Customer IDs

Returns unique customer identifiers seen in events, classified as internal or external and paired when possible.

GET https://api.getlumen.dev/v1/events/unique-customer-ids

Response

{
  "customerIds": [
    { "id": "ext_abc", "externalId": "ext_abc", "internalId": "cust_123", "name": "Jane", "email": "jane@example.com", "type": "customer" },
    { "id": "cust_456", "internalId": "cust_456", "name": "John", "email": "john@example.com", "type": "customer" },
    { "id": "unknown_1", "type": "unknown" }
  ]
}

Back-fill (Admin Only)

POST https://api.getlumen.dev/v1/trigger/events-backfill

Migrates older PostgreSQL data into QuestDB. The endpoint is not intended for general use; access is restricted to authenticated merchants and typically executed via CLI tooling.

Body

Response:

{ "scanned": 1200, "inserted": 1189 }

Relationship to Entitlements API

The Entitlements engine consumes the aggregated usage derived from the events you send here. For metered features (value is numeric) the allowance versus usage is evaluated in real-time. Sending accurate events therefore ensures that:

1. Usage Limits in the Entitlements API are correct.
2. Credit depletion and expiry behave as expected.
3. Analytics dashboards reflect customer activity.

No additional integration steps are required – once events are recorded, entitlement checks will automatically include the latest usage totals.

Best Practices

1. Choose stable eventNames – changing the slug creates new metrics.
2. Send events immediately – delays reduce the accuracy of real-time limits.
3. Include an idempotencyKey when retrying failed requests.
4. Batch when possible to reduce network overhead.
5. Validate input on the client side to avoid 400 errors.

Error Handling Cheat-Sheet

Changelog