---
title: "Usage and spend caps"
sidebarTitle: "Usage and billing"
description: "Trillet OEM usage per tenant and per call, how tenants are billed, and monthly spend caps."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

<Note>
  **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.
</Note>

## 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](https://trillet-ai.jamdesk.app/voice-engine/authentication#restricting-a-key-to-some-tenants) sees only those tenants.

### Totals

```bash
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_..."
```

```json
{
  "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

```bash
curl "https://api.trillet.ai/partner/v1/usage/calls?tenantId=d9d9d9d9d9d9d9d9d9d9d9d9&limit=100" \
  -H "Authorization: Bearer tpk_live_..."
```

```json
{
  "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](https://trillet-ai.jamdesk.app/voice-engine/events#event-shape) 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}`](https://trillet-ai.jamdesk.app/voice-engine/tenants#update-a-tenant) | One tenant |
| Account cap | Trillet, on request through your account manager | The total across all of your tenants |

```bash
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](https://trillet-ai.jamdesk.app/voice-engine/events) is sent, once per cap per month:

```json
{
  "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%](#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.

<Note>
  A partner invoices endpoint and concurrency and outbound pacing limits per tenant are planned.
</Note>
