Usage Events API — ingest metered usage data

Usage events are the raw data that meters aggregate into billable quantities. Send an event every time a metered action occurs — an API call, a file upload, a message sent. Borga matches each event to the appropriate meter by event_name and accumulates usage for invoicing.

Always set idempotency_key on every event you ingest. If a network failure causes your request to time out, you can retry the same payload safely — Borga will deduplicate events with the same key and never count them twice.

Ingest a single event

POST /v1/events Ingests one usage event.

Request parameters

string

required

Name of the event. Must match the event_name configured on a meter. Maximum 200 characters.

string

ID of the Borga customer this event belongs to. Either customer or external_customer_id must be provided.

string

Your own identifier for the customer. Borga will resolve this to a Borga customer ID. Either customer or external_customer_id must be provided.

string

A unique string for this event. If you send two events with the same key, only the first is recorded. Maximum 200 characters. Recommended for all production ingestion.

string

ISO 8601 timestamp indicating when the event occurred. Defaults to the current time if omitted. Use this to backfill historical events.

object

Arbitrary key-value pairs describing the event. For meters with aggregate_type other than count, the aggregate_property value is read from this object.

curl --request POST \
  --url https://api.borga.is/v1/events \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "event_name": "api.request",
    "customer": "cus_abc123",
    "idempotency_key": "req_2026-04-29-00001",
    "timestamp": "2026-04-29T10:15:00Z",
    "metadata": {
      "endpoint": "/v1/payments",
      "method": "POST"
    }
  }'

Response fields

string

required

Unique identifier assigned to this event.

string

required

Name of the ingested event.

string

required

ID of the customer this event is associated with.

string

The idempotency key provided with this event.

string

required

ISO 8601 timestamp of when the event occurred.

object

Key-value pairs attached to the event.

{
  "id": "evt_01hx9z3k2mfq7nbvd4cw8ej001",
  "event_name": "api.request",
  "customer": "cus_abc123",
  "idempotency_key": "req_2026-04-29-00001",
  "timestamp": "2026-04-29T10:15:00Z",
  "metadata": {
    "endpoint": "/v1/payments",
    "method": "POST"
  }
}

Ingest a batch of events

POST /v1/events/batch Ingests up to 1,000 events in a single request. Borga processes each event independently — if one event fails validation, the others are still ingested.

Each batch request can contain a maximum of 1,000 events. If you need to send more, split them across multiple batch requests.

Request parameters

object[]

required

Array of event objects to ingest. Minimum 1, maximum 1,000 items. Each object accepts the same fields as a single event ingestion request.

Show IngestEventDto fields

string

required

Name of the event. Maximum 200 characters.

string

ID of the Borga customer this event belongs to.

string

Your own identifier for the customer.

string

Unique key for deduplication. Maximum 200 characters.

string

ISO 8601 timestamp of when the event occurred.

object

Arbitrary key-value pairs describing the event.

curl --request POST \
  --url https://api.borga.is/v1/events/batch \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      {
        "event_name": "api.request",
        "customer": "cus_abc123",
        "idempotency_key": "req_2026-04-29-00002",
        "timestamp": "2026-04-29T10:16:00Z",
        "metadata": { "endpoint": "/v1/subscriptions", "method": "GET" }
      },
      {
        "event_name": "api.request",
        "customer": "cus_abc123",
        "idempotency_key": "req_2026-04-29-00003",
        "timestamp": "2026-04-29T10:17:00Z",
        "metadata": { "endpoint": "/v1/events", "method": "POST" }
      }
    ]
  }'

Response fields

number

required

Number of events successfully ingested.

object[]

Array of error objects for any events that failed validation. Each object includes an index indicating which event in the request array failed, and a message describing the error.

{
  "ingested": 2,
  "errors": []
}

List events

GET /v1/events Returns a paginated list of ingested events, ordered by timestamp descending.

Query parameters

string

Filter events by customer ID.

string

Filter events by event name.

string

Return only events at or after this ISO 8601 timestamp.

string

Return only events at or before this ISO 8601 timestamp.

string

Cursor for pagination. Pass the id of the last event from the previous page to retrieve the next page.

number

Maximum number of events to return per page.

curl --request GET \
  --url "https://api.borga.is/v1/events?customer=cus_abc123&event_name=api.request&from=2026-04-01T00%3A00%3A00Z&limit=50" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

Response fields

object[]

required

Array of event objects. Each object has the same fields as the single event response above.

boolean

required

Whether more events exist beyond this page. Pass the last id as starting_after to retrieve the next page.

Overview

Payments

Subscriptions

Billing

Configuration

Usage Events API — ingest metered usage data

Ingest a single event

Request parameters

Response fields

Ingest a batch of events

Request parameters

Response fields

List events

Query parameters

Response fields

​Ingest a single event

​Request parameters

​Response fields

​Ingest a batch of events

​Request parameters

​Response fields

​List events

​Query parameters

​Response fields

Ingest a single event

Request parameters

Response fields

Ingest a batch of events

Request parameters

Response fields

List events

Query parameters

Response fields