Usage Events & Ingestion

Usage events are the raw consumption records that feed into BillHive’s usage-based billing pipeline. Each event represents a discrete action performed by a customer — an API call, bytes of storage consumed, a message sent, or tokens processed.

Usage Event Structure

BillHive uses a schema-less event model. Events accept arbitrary properties as JSON without requiring predefined schemas, allowing you to send raw data exactly as your system produces it.

Core Fields

Example Event

{
  "event_id": "evt_abc123_2026030614",
  "event_type": "api_call",
  "subscription_id": "sub_01HXYZ",
  "account_id": "cust_01HABC",
  "quantity": 1,
  "timestamp": "2026-03-06T14:30:00Z",
  "properties": {
    "endpoint": "/v1/translate",
    "method": "POST",
    "response_status": 200,
    "tokens_input": 150,
    "tokens_output": 45
  }
}

Deduplication

BillHive uses the event_id as an idempotency key. If an event with the same event_id is submitted more than once for the same tenant, the duplicate is rejected. This ensures safe retries without double-counting usage.

Best practice: Construct event_id values that are naturally unique and deterministic, such as combining a transaction ID with a timestamp: txn_12345_20260306143000.

Ingestion Methods

1. REST API (Single Event)

Send individual usage events in real-time as consumption occurs.

POST /api/usage-events
Content-Type: application/json
 
{
  "event_id": "evt_001",
  "event_type": "api_call",
  "subscription_id": "sub_01HXYZ",
  "account_id": "cust_01HABC",
  "quantity": 1,
  "timestamp": "2026-03-06T14:30:00Z",
  "properties": { "endpoint": "/v1/translate" }
}

2. REST API (Batch)

Send multiple events in a single request for higher throughput.

POST /api/usage-events/batch
Content-Type: application/json
 
{
  "events": [
    {
      "event_id": "evt_001",
      "event_type": "api_call",
      "subscription_id": "sub_01HXYZ",
      "account_id": "cust_01HABC",
      "quantity": 1,
      "timestamp": "2026-03-06T14:30:00Z",
      "properties": {}
    },
    {
      "event_id": "evt_002",
      "event_type": "api_call",
      "subscription_id": "sub_01HXYZ",
      "account_id": "cust_01HABC",
      "quantity": 1,
      "timestamp": "2026-03-06T14:31:00Z",
      "properties": {}
    }
  ]
}

Batch limits: Up to 1,000 events per batch request.

3. CSV Bulk Import

Upload historical data or large volumes of usage records via CSV file.

Required CSV columns:

• event_id
• timestamp
• subscription_id
• accountId

Additional columns are treated as event properties.

Constraints:

• Maximum file size: 5 MB per upload
• No automatic validation against existing subscriptions — ensure data quality before import
• Failed rows are reported separately with failure reasons for reprocessing

4. Manual UI Entry

Enter individual usage records directly through the BillHive interface. Suitable for small datasets, adjustments, or testing.

Event Statuses

Usage Recorded After the Term Ends

Usage for a term can arrive after the term has ended. The Usage Data Entry Grace Period in Subscription Settings decides how long it is still accepted for that term:

The grace period is 0 days unless you set it, so usage recorded after the term ends is Invalid by default.

Event Sources

Rate Limits

Best Practices

1. Use deterministic event IDs — Construct IDs from transaction data so retries are naturally idempotent
2. Send events in near real-time — Minimize delay between consumption and ingestion for accurate mid-cycle usage summaries
3. Use batch API for high-volume ingestion — Reduces HTTP overhead and improves throughput
4. Include rich properties — Add metadata (region, tier, feature, endpoint) to enable flexible filtering in metered features
5. Validate before CSV import — BillHive does not validate CSV data against existing subscriptions; ensure IDs are correct before uploading
6. Monitor event statuses — Check for INVALID or DUPLICATE events to catch integration issues early

Viewing Usage Events

Usage events can be viewed and filtered from the Usage page under the Usage Events tab. The enriched view shows event details alongside subscription name, account name, and term dates. Filter by:

• Event type
• Event status
• Source
• Date range

Events can also be exported to Excel or printed from the toolbar.

Usage Event Batches

When using the batch API or CSV import, BillHive creates a batch record that tracks:

View batch records from the Usage Event Batches API endpoint.