Docs
API reference/Usage-based billing

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 },
  },
]);
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. The request body must stay under 1 MB, which a full batch with a short metadata object does comfortably.
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: every event is validated before anything is written, and the accepted events are stored in one statement. An error names the offending item in param, for example events[12].timestamp. The response counts inserted and duplicates; an event whose idempotency_key was seen before, in this batch or an earlier one, is a duplicate.

Errors: validation_failed, future_timestamp, resource_not_found for customer, request_too_large when the body is over 1 MB.

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