Usage reporting
TelAPI exposes a small usage-reporting surface for integrations that need team-level consumption data outside TelWeb.
TTS characters
GET /api/v1/usage/tts-characters returns aggregated TTS character consumption for the API key's team.
Required scope: READ_TEAM_USAGE.
Query parameters:
| Parameter | Description |
|---|---|
timeframe | today, week, month, year, or total. |
from | Optional ISO 8601 lower bound. Use with to for a custom window. |
to | Optional ISO 8601 upper bound. Use with from for a custom window. |
Response fields:
| Field | Description |
|---|---|
teamId | Team whose usage was queried. |
timeframe | Effective timeframe. |
from / to | Effective ISO 8601 time window. |
charactersTotal | Total TTS characters. |
charactersFromCache | Characters served from the TTS media cache. |
charactersGenerated | Characters newly generated by TTS providers. |
cacheHitRatio | Cached share of total characters, when enough data is available. |
Use API keys to grant READ_TEAM_USAGE only to reporting integrations that need this endpoint.
See also
- Scopes — API-key permission model.
- Dashboard — TelWeb TTS character widget.
- API reference — generated schemas when the OpenAPI snapshot is available.