Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.borga.is/llms.txt

Use this file to discover all available pages before exploring further.

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

​
event_name
string
required
Name of the event. Must match the event_name configured on a meter. Maximum 200 characters.
​
customer
string
ID of the Borga customer this event belongs to. Either customer or external_customer_id must be provided.
​
external_customer_id
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.
​
idempotency_key
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.
​
timestamp
string
ISO 8601 timestamp indicating when the event occurred. Defaults to the current time if omitted. Use this to backfill historical events.
​
metadata
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

​
id
string
required
Unique identifier assigned to this event.
​
event_name
string
required
Name of the ingested event.
​
customer
string
required
ID of the customer this event is associated with.
​
idempotency_key
string
The idempotency key provided with this event.
​
timestamp
string
required
ISO 8601 timestamp of when the event occurred.
​
metadata
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

​
events
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.
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

​
ingested
number
required
Number of events successfully ingested.
​
errors
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

​
customer
string
Filter events by customer ID.
​
event_name
string
Filter events by event name.
​
from
string
Return only events at or after this ISO 8601 timestamp.
​
to
string
Return only events at or before this ISO 8601 timestamp.
​
starting_after
string
Cursor for pagination. Pass the id of the last event from the previous page to retrieve the next page.
​
limit
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

​
data
object[]
required
Array of event objects. Each object has the same fields as the single event response above.
​
has_more
boolean
required
Whether more events exist beyond this page. Pass the last id as starting_after to retrieve the next page.