Retained reference snapshot. This independently versioned API snapshot does not select or advance a platform or SDK release.
GET /api/v1/usage/tts-characters
Get total TTS character consumption for the calling team
Available when Browser SDK is enabled; WebRTC is not required. Returns the aggregated TTS character ingestion (total, cached, generated, cache-hit ratio) for the team that owns the API key, within the requested [from, to] window. Apps that are excluded from the dashboard are not included in the aggregation. Requires a team API key with the READ_TEAM_USAGE scope.
Request, response and operation contract
{
"summary": "Get total TTS character consumption for the calling team",
"tags": ["Usage"],
"description": "Available when Browser SDK is enabled; WebRTC is not required. Returns the aggregated TTS character ingestion (total, cached, generated, cache-hit ratio) for the team that owns the API key, within the requested [from, to] window. Apps that are excluded from the dashboard are not included in the aggregation. Requires a team API key with the READ_TEAM_USAGE scope.",
"parameters": [
{
"schema": {
"type": "string",
"format": "date-time"
},
"in": "query",
"name": "from",
"required": false,
"description": "Start of the report window (ISO 8601). Defaults to epoch if both from and to are omitted."
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"in": "query",
"name": "to",
"required": false,
"description": "End of the report window (ISO 8601). Defaults to \"now\" if both from and to are omitted."
},
{
"schema": {
"type": "string",
"enum": ["day", "week", "month", "total"],
"default": "total"
},
"in": "query",
"name": "timeframe",
"required": false,
"description": "Timeframe label echoed in the response (does not change aggregation; informational)."
}
],
"security": [
{
"apiKey": []
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"teamId",
"timeframe",
"from",
"to",
"charactersTotal",
"charactersFromCache",
"charactersGenerated"
],
"properties": {
"teamId": {
"type": "string",
"format": "uuid",
"description": "The team the API key belongs to."
},
"timeframe": {
"type": "string",
"enum": ["day", "week", "month", "total"]
},
"from": {
"type": "string",
"format": "date-time",
"description": "Resolved start of the report window."
},
"to": {
"type": "string",
"format": "date-time",
"description": "Resolved end of the report window."
},
"charactersTotal": {
"type": "integer",
"minimum": 0,
"description": "Total TTS characters synthesised in the window (cached + generated)."
},
"charactersFromCache": {
"type": "integer",
"minimum": 0,
"description": "TTS characters served from the media cache."
},
"charactersGenerated": {
"type": "integer",
"minimum": 0,
"description": "TTS characters generated by the upstream provider."
},
"cacheHitRatio": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "charactersFromCache / charactersTotal, rounded to 4 decimal places. 0 when no characters were processed."
}
}
},
"example": {
"teamId": "5e2c1f04-6a3b-4d6f-8b1d-9c1b8b1b8b1b",
"timeframe": "total",
"from": "2026-06-01T00:00:00.000Z",
"to": "2026-07-01T00:00:00.000Z",
"charactersTotal": 12345,
"charactersFromCache": 4321,
"charactersGenerated": 8024,
"cacheHitRatio": 0.35
}
}
}
},
"400": {
"description": "Request validation failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Request validation failed",
"required": ["error"],
"properties": {
"error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable error summary.",
"example": "Request validation failed"
},
"details": {
"description": "Optional structured details, usually validation issues."
},
"requestId": {
"type": "string",
"description": "Fastify request id for log correlation when available."
}
}
}
}
},
"example": {
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed"
}
}
}
}
},
"401": {
"description": "API key is missing or invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "API key is missing or invalid",
"required": ["error"],
"properties": {
"error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable error summary.",
"example": "Request validation failed"
},
"details": {
"description": "Optional structured details, usually validation issues."
},
"requestId": {
"type": "string",
"description": "Fastify request id for log correlation when available."
}
}
}
}
},
"example": {
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "API key is missing or invalid"
}
}
}
}
},
"403": {
"description": "API key lacks the required scope or resource access",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "API key lacks the required scope or resource access",
"required": ["error"],
"properties": {
"error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable error summary.",
"example": "Request validation failed"
},
"details": {
"description": "Optional structured details, usually validation issues."
},
"requestId": {
"type": "string",
"description": "Fastify request id for log correlation when available."
}
}
}
}
},
"example": {
"error": {
"code": "AUTHORIZATION_ERROR",
"message": "API key lacks the required scope or resource access"
}
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Too many requests",
"required": ["error"],
"properties": {
"error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable error summary.",
"example": "Request validation failed"
},
"details": {
"description": "Optional structured details, usually validation issues."
},
"requestId": {
"type": "string",
"description": "Fastify request id for log correlation when available."
}
}
}
}
},
"example": {
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests"
}
}
}
}
},
"500": {
"description": "Unexpected server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Unexpected server error",
"required": ["error"],
"properties": {
"error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable error summary.",
"example": "Request validation failed"
},
"details": {
"description": "Optional structured details, usually validation issues."
},
"requestId": {
"type": "string",
"description": "Fastify request id for log correlation when available."
}
}
}
}
},
"example": {
"error": {
"code": "INTERNAL_ERROR",
"message": "Unexpected server error"
}
}
}
}
}
}
}
Shared path-item configuration
{}
Effective document defaults
{
"servers": [],
"security": []
}
Resolve local schema references in the component catalogue or the exact OpenAPI download. Operation and path-item overrides retain their OpenAPI meaning; omitted security is not a declaration that authentication is unnecessary.