Usage events

Report what customers consume. Events are matched to meters by name and aggregated at period end.

Usage events live at /v1/events. They are the raw input to meters, and are unrelated to webhook events, which are delivered to you rather than read from the API.

The usage event object

idstring

Prefixed ue_.

objectstring

usage_event

event_namestring

customerstring | null

Resolved customer, from customer or external_customer_id.

external_customer_idstring | null

timestamptimestamp

metadataobject

idempotency_keystring | null

created_attimestamp

Ingest one event

POST/v1/eventsSecret key

Body

event_namestringrequired

Matches a meter's event_name. Up to 200 characters.

customerstring

The cus_ id. Provide this or external_customer_id.

external_customer_idstring

Your id, matched to Customer.external_id. Unmatched events are stored and linked when the customer is created.

timestamptimestamp

Defaults to now. Rejected if more than 60 seconds in the future.

idempotency_keystring

Dedup key, up to 200 characters. Repeats are dropped and counted in duplicates.

metadataobject

Values a meter's aggregate_property and filter refer to.

Node.jsts

// Single event
await borga.usageEvents.create({
  event_name: "api_request",
  customer: "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
  idempotency_key: "req_01J9X2K7M3", // dedupes retries
  metadata: { endpoint: "/v1/chat" },
});

// Batches of up to 1000, identified by your own customer ids
await borga.usageEvents.createBatch([
  {
    event_name: "llm_completion",
    external_customer_id: "user_12345",
    timestamp: "2026-09-07T12:00:00Z",
    idempotency_key: "cmpl_a1",
    metadata: { total_tokens: 640 },
  },
  {
    event_name: "llm_completion",
    external_customer_id: "user_12345",
    timestamp: "2026-09-07T12:00:02Z",
    idempotency_key: "cmpl_a2",
    metadata: { total_tokens: 1024 },
  },
]);

curlbash

curl https://api.borga.is/v1/events \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api_request",
    "customer": "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
    "idempotency_key": "req_01J9X2K7M3",
    "metadata": { "endpoint": "/v1/chat" }
  }'

Response

{ "inserted": 1, "duplicates": 0 }

Errors: invalid_timestamp, future_timestamp, resource_not_found for customer.

Ingest a batch

POST/v1/events/batchSecret key

Body

eventsarrayrequired

1 to 1000 event objects with the fields above.

curl https://api.borga.is/v1/events/batch \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_name": "api_request", "external_customer_id": "user_12345", "idempotency_key": "req_1" },
      { "event_name": "api_request", "external_customer_id": "user_12345", "idempotency_key": "req_2" }
    ]
  }'

The whole batch is accepted or rejected together; the response counts inserted and duplicates.

List usage events

GET/v1/eventsSecret key

Newest first by timestamp.

Query parameters

customerstring

event_namestring

fromtimestamp

Inclusive lower bound on timestamp.

totimestamp

Exclusive upper bound on timestamp.

limitintegerdefault: 25

starting_afterstring