Trillet AI logo

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

MethodPathScopeReturns
GET/partner/v1/usageusage:readTotals by day or month, per tenant or per charge type
GET/partner/v1/usage/callsusage:readOne row per call charge

Both accept:

ParameterNotes
fromStart, ISO 8601 date-time, inclusive. Default: the start of the current month (UTC).
toEnd, ISO 8601 date-time, exclusive. Default: now.
tenantIdOnly 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
    }
  ]
}
ParameterValues
groupBytenant (default) or type. With type, each row has type instead of tenantId.
granularityday (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:

typeWhat
call_chargeVoice calls
message_chargeChat and messaging
sms_chargeSMS
voice_generation_chargeVoice generation
antibot_detection_chargeBot detection
workflow_chargeWorkflow runs
phone_number_charge, phone_number_purchasePhone 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.

FieldNotes
idThe charge ID. Use it as starting_after.
callHistoryIdThe 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.
callIdTrillet's internal call identifier, kept for reference. Use callHistoryId to join with events and call history.
billedSecondsThe call time charged
ratePerMinuteThe per-minute rate applied. Telephony and other surcharges are in amount, not in the rate.
amountThe charge in USD

Spend caps

A spend cap limits a month's usage, from the first of the month (UTC). There are two:

CapSet byApplies to
Tenant capYou, with limits.monthlySpendCap on PATCH /tenants/{tenantId}One tenant
Account capTrillet, on request through your account managerThe 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 (402 insufficient_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