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 team that owns the calling API key. The endpoint is scoped to that team and does not accept a team identifier in the query string.
Required scope: READ_TEAM_USAGE.
Query parameters:
| Parameter | Description |
|---|---|
timeframe | Informational label echoed in the response. Supported values are day, week, month, and 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 label. |
from / to | Effective ISO 8601 time window. |
charactersTotal | Total TTS characters processed in the window (cached + generated). |
charactersFromCache | TTS characters served from the media cache. |
charactersGenerated | TTS characters generated by an upstream provider. |
cacheHitRatio | Cached share of total characters, rounded to 4 decimal places. |
The endpoint excludes apps marked as excluded from the dashboard so the numbers stay aligned with the TelWeb TTS widget. 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.