Get total TTS character consumption for the calling team

Snapshot: 0.9.17-patch1 · selected operations. This is a stored schema reference, not a fresh export or confirmation of behavior in another release. Scope and availability.

Availability and authentication

API access must be enabled for your deployment. Ask the platform administrator to confirm availability and the required API-key scope documented in the operation description below. Send the team API key in the X-API-Key header. Enabled interaction modes depend on endpoint runtime capabilities; the export profile does not enable them in your deployment.

GET /api/v1/usage/tts-characters

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

Name	Location	Required	Description	Schema
from	query	No	Start of the report window (ISO 8601). Defaults to epoch if both from and to are omitted.	{"type":"string","format":"date-time"}
to	query	No	End of the report window (ISO 8601). Defaults to "now" if both from and to are omitted.	{"type":"string","format":"date-time"}
timeframe	query	No	Timeframe label echoed in the response (does not change aggregation; informational).	{"type":"string","enum":["day","week","month","total"],"default":"total"}

Responses

These are declared schema responses, not results of live requests. An example is illustrative, not a complete catalogue of possible errors.

Status	Description
200	Default Response
400	Request validation failed
401	API key is missing or invalid
403	API key lacks the required scope or resource access
429	Too many requests
500	Unexpected server error

200

Default Response

Content type: application/json.

Required means required within its containing object. Exact schema below retains all constraints and alternatives.

Field	Type	Required	Description	Constraints
teamId	string	Yes	The team the API key belongs to.	format: "uuid"
timeframe	string	Yes	Not described in snapshot.	enum: ["day","week","month","total"]
from	string	Yes	Resolved start of the report window.	format: "date-time"
to	string	Yes	Resolved end of the report window.	format: "date-time"
charactersTotal	integer	Yes	Total TTS characters synthesised in the window (cached + generated).	minimum: 0
charactersFromCache	integer	Yes	TTS characters served from the media cache.	minimum: 0
charactersGenerated	integer	Yes	TTS characters generated by the upstream provider.	minimum: 0
cacheHitRatio	number	No	charactersFromCache / charactersTotal, rounded to 4 decimal places. 0 when no characters were processed.	minimum: 0; maximum: 1

Exact response schema and examples

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

Request validation failed

Exact response schema and examples

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

API key is missing or invalid

Exact response schema and examples

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

API key lacks the required scope or resource access

Exact response schema and examples

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

Too many requests

Exact response schema and examples

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

Unexpected server error

Exact response schema and examples

{
  "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"
        }
      }
    }
  }
}

Machine-readable reference

Download the selected OpenAPI operations. The download contains this subset only.