Every error names the field and the fix, for example: quantity must be a positive number — received -3.
Sending usage
API reference
Every endpoint, every field, every error.
9 min read
Authentication
Send your key as a bearer token. Keys are hashed at rest, can be revoked at any time, and record when they were last used.
| Prefix | Scope | Can do |
|---|---|---|
| pk_live_ | ingest | POST /v1/events only |
| sk_live_ | full | Everything, including reads and plan uploads |
POST /v1/events
Accepts a single event object or an array of up to 500. Duplicate event_id values within seven days are dropped silently, so retries are safe.
| Field | Type | Notes |
|---|---|---|
| event_id | string (uuid) | Yours. Used for deduplication. |
| event_type | string | call | sms | api_call | tokens | anything you like |
| timestamp | string (ISO 8601) | Stored as UTC. More than 5 minutes in the future is rejected. |
| account | string | Your own customer identifier. |
| quantity | number | Zero rates as zero. Negative is rejected unless the plan allows credits. |
| unit | string | seconds | messages | requests | tokens | anything |
| properties | object | Free-form. The rating engine matches against one of these. |
GET /v1/usage/summary
Requires from, to and group_by. group_by is one of account, event_type or day.
{
"rows": [
{ "bucket": "acct_alphacomms", "usage_quantity": 52502312, "amount": 24531.22 },
{ "bucket": "acct_nebulalabs", "usage_quantity": 39016694, "amount": 18232.10 }
]
}GET /v1/events/:event_id
The drill-down. Returns the raw event joined to its rated row. Rating fields are null until the worker has rated the event; is_unrated is 1 when it was rated but no tariff line matched.
{
"event_id": "5f0c1d84-6b1e-4a0e-9c7d-2e4b8f1a3c55",
"event_type": "call",
"ts": "2024-05-27 14:02:11.000",
"account": "acct_alphacomms",
"quantity": 372,
"unit": "seconds",
"properties_json": "{\"destination\":\"447700900123\"}",
"amount": 0.1562,
"rate_applied": 0.00042,
"plan_version": "9a1f2c74-5e33-4b90-bd21-77c0e4a1f8d2",
"matched_key": "447",
"currency": "GBP",
"is_unrated": 0,
"unrated_reason": ""
}GET /v1/accounts/:account/statement
Takes month as YYYY-MM. Returns the account's total for that period.
{
"account": "acct_alphacomms",
"month": "2024-05",
"total_amount": 52290.75,
"total_quantity": 111902205,
"currency": "GBP"
}Rate limits
Limits are per key. Exceeding one returns 429 with a Retry-After header. The ingest endpoint is sized for sustained bulk traffic; the read endpoints are sized for dashboards.