Usage and spend caps
Trillet OEM usage per tenant and per call, how tenants are billed, and monthly spend caps.
Early access. Trillet OEM is built and in testing with design partners. Contact your account manager to have it enabled for your account. Details may still change.
How you are billed
Tenants are billed to your partner account at the standard Trillet rates, the same rates every Trillet customer pays: calls start at $0.12 per minute and phone numbers start at $4.99 per month. Each tenant's wallet is linked to your account, so your tenants do not need cards or balances on Trillet. Charges are drawn from your account balance, or recorded and invoiced to you if your account is set up for invoicing.
Usage amounts in this API are what Trillet charges your account. What you charge your own customers is up to you and is not stored on Trillet.
Endpoints
| Method | Path | Scope | Returns |
|---|---|---|---|
GET | /partner/v1/usage | usage:read | Totals by day or month, per tenant or per charge type |
GET | /partner/v1/usage/calls | usage:read | One row per call charge |
Both accept:
| Parameter | Notes |
|---|---|
from | Start, ISO 8601 date-time, inclusive. Default: the start of the current month (UTC). |
to | End, ISO 8601 date-time, exclusive. Default: now. |
tenantId | Only this tenant |
A range can cover up to 92 days. A bad range returns 400 invalid_range. Usage includes deleted tenants, so past months stay complete. A key restricted to some tenants sees only those tenants.
Totals
curl "https://api.trillet.ai/partner/v1/usage?from=2026-11-01T00:00:00Z&to=2026-12-01T00:00:00Z&granularity=month&groupBy=tenant" \
-H "Authorization: Bearer tpk_live_..."
{
"object": "usage",
"from": "2026-11-01T00:00:00.000Z",
"to": "2026-12-01T00:00:00.000Z",
"currency": "usd",
"groupBy": "tenant",
"granularity": "month",
"total": 241.17,
"data": [
{
"period": "2026-11",
"tenantId": "d9d9d9d9d9d9d9d9d9d9d9d9",
"amount": 241.17,
"count": 655,
"billedMinutes": 1030.67
}
]
}
| Parameter | Values |
|---|---|
groupBy | tenant (default) or type. With type, each row has type instead of tenantId. |
granularity | day (default, period is YYYY-MM-DD) or month (period is YYYY-MM). Periods are UTC. |
Each row has amount (USD), count (number of charges) and, when the charges include call time, billedMinutes. The charge types counted as usage are:
type | What |
|---|---|
call_charge | Voice calls |
message_charge | Chat and messaging |
sms_charge | SMS |
voice_generation_charge | Voice generation |
antibot_detection_charge | Bot detection |
workflow_charge | Workflow runs |
phone_number_charge, phone_number_purchase | Phone numbers |
Account-level fees, such as plan and white-label fees, are not tenant usage and are not included.
Per call
curl "https://api.trillet.ai/partner/v1/usage/calls?tenantId=d9d9d9d9d9d9d9d9d9d9d9d9&limit=100" \
-H "Authorization: Bearer tpk_live_..."
{
"object": "list",
"data": [
{
"id": "e7e7e7e7e7e7e7e7e7e7e7e7",
"tenantId": "d9d9d9d9d9d9d9d9d9d9d9d9",
"callId": "SCL_q4Zt8vXbN2kP",
"callHistoryId": "e5e5e5e5e5e5e5e5e5e5e5e5",
"at": "2026-11-02T15:04:12.000Z",
"billedSeconds": 151,
"ratePerMinute": 0.12,
"amount": 0.302
}
],
"hasMore": true
}
Rows are newest first. Page with limit (1 to 200, default 50) and starting_after set to the last row's id.
| Field | Notes |
|---|---|
id | The charge ID. Use it as starting_after. |
callHistoryId | The call history ID. It matches data.call.id in call events and works with GET /v2/api/call-history/{callHistoryId} and GET /v2/api/recordings/{callHistoryId}. null when the call record cannot be matched. |
callId | Trillet's internal call identifier, kept for reference. Use callHistoryId to join with events and call history. |
billedSeconds | The call time charged |
ratePerMinute | The per-minute rate applied. Telephony and other surcharges are in amount, not in the rate. |
amount | The charge in USD |
Spend caps
A spend cap limits a month's usage, from the first of the month (UTC). There are two:
| Cap | Set by | Applies to |
|---|---|---|
| Tenant cap | You, with limits.monthlySpendCap on PATCH /tenants/{tenantId} | One tenant |
| Account cap | Trillet, on request through your account manager | The total across all of your tenants |
curl -X PATCH https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9 \
-H "Authorization: Bearer tpk_live_..." \
-H "Content-Type: application/json" \
-d '{ "limits": { "monthlySpendCap": 500 } }'
Set monthlySpendCap to null to remove a tenant cap. A cap of 0 blocks all paid work for the tenant.
Alerts
When month-to-date usage reaches 80% of a cap, and again at 100%, a usage.threshold_reached event is sent, once per cap per month:
{
"id": "evt_e8e8e8e8e8e8e8e8e8e8e8e8",
"type": "usage.threshold_reached",
"created": 1762095851,
"livemode": true,
"tenant": { "id": "d9d9d9d9d9d9d9d9d9d9d9d9", "externalId": "cust_8842" },
"data": { "scope": "tenant", "percent": 80, "cap": 500, "monthToDate": 401.25, "month": "2026-11" }
}
scope is tenant or partner. For the account cap, tenant is null.
Caps are not checked on a schedule. Trillet checks a cap, and sends these alerts, only when one of the paid actions listed under At 100% is about to run. So:
- A tenant with only inbound calls gets no alert, even though its inbound usage counts towards its month-to-date spend. The alert comes with its next paid action.
- If usage goes from under 80% to over 100% between two checks, only the 100% alert is sent.
- With a cap of
0, the 100% alert is sent on the tenant's first paid action.
At 100%
Once a tenant reaches its cap, or your account reaches the account cap, these are refused for the rest of the month, as if the account had no funds:
- outbound calls and web calls
- SMS, including chat and SMS replies
- WhatsApp calls
- workflow runs
- batch calls
- buying phone numbers (
402insufficient_funds)
Inbound phone calls continue, so a business's line keeps working. Raise or remove the cap to restore service straight away.
Usage totals for caps are refreshed about once a minute, so a burst of activity can go slightly past a cap before it is enforced.
A partner invoices endpoint and concurrency and outbound pacing limits per tenant are planned.
Last updated on