Lumen Documentation

Send multiple usage events in a single request (max 100). Each event follows the single-ingest validation rules and is deduplicated individually by idempotencyKey for 24 hours.

Authorization

bearerAuth

AuthorizationBearer <token>

Use your secret API key as the bearer token

In: header

Request Body

application/json

events*

Array of events to ingest (max 100).

Items1 <= items <= 100

Response Body

`application/json`

curl -X POST "https://api.getlumen.dev/v1/events/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "eventName": "api-call",
        "customerId": "cus_Lo4xGg1Yk9pB2eWv3sNt",
        "eventValue": 1,
        "idempotencyKey": "evt_batch_001"
      },
      {
        "eventName": "user-login",
        "extCustomerId": "user_ext_789",
        "eventString": "user_ext_789",
        "idempotencyKey": "evt_batch_002"
      }
    ]
  }'

curl -X POST "https://api.getlumen.dev/v1/events/batch" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "eventName": "api-call",        "customerId": "cus_Lo4xGg1Yk9pB2eWv3sNt",        "eventValue": 1,        "idempotencyKey": "evt_batch_001"      },      {        "eventName": "user-login",        "extCustomerId": "user_ext_789",        "eventString": "user_ext_789",        "idempotencyKey": "evt_batch_002"      }    ]  }'

{
  "accepted": 1,
  "rejected": 1,
  "errors": [
    {
      "index": 1,
      "error": "Provide customerId or extCustomerId and exactly one of eventValue or eventString"
    }
  ]
}

{
  "error": "Invalid batch payload",
  "details": "Send between 1 and 100 events"
}

{
  "error": "Failed to ingest events"
}

Batch Ingest Events

Authorization

Request Body

Response Body

202application/json

400application/json

500application/json

`application/json`

`application/json`

`application/json`