Recording Usage
Send usage events to HL Hunt to track customer consumption in real-time.
Sending Events
Send events to the HL Hunt ingestion endpoint. The customer and usage value travel inside the payload object — not at the top level:
- event_name — must match a meter's event name
- payload.customer_id — the customer being billed (key configurable via the meter's
customer_mapping.event_payload_key) - payload.value — the numeric usage amount (not needed on
countmeters) - identifier (optional, recommended) — for deduplication
- timestamp (optional) — when the usage occurred; defaults to server-receive time
POST /v1/billing/meter-events
{
"event_name": "api_call",
"identifier": "req_xyz789",
"timestamp": "2026-06-22T10:30:00Z",
"payload": { "customer_id": "cus_abc123", "value": 1 }
}Event Format
| Field | Type | Required |
|---|---|---|
| event_name | string | Yes |
| payload.customer_id | string | Yes |
| payload.value | number | Except count meters |
| identifier | string, ≤ 200 chars | No (recommended) |
| timestamp | ISO 8601, within −35 days to +5 min | No |
Deduplication
Use the identifier field to prevent duplicate events. A repeat of the same (event_name, identifier) pair within 24 hours is a no-op — the server returns the original event instead of writing a new row.
This is useful for retrying failed API calls without accidentally double-counting usage.
Rate Limits
The ingestion endpoint supports up to 60,000 events per minute per API key. For high-throughput scenarios, batch events together.