> ## Documentation Index > Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Get usage > Bucketed usage analytics with breakdowns by voice, API key, or model — ideal for dashboards and reporting. Returns generated-audio minutes aggregated into time buckets, optionally broken down by voice, API key, or model. Use this for dashboards, internal reporting, and per-key attribution. For a simpler per-voice rollup keyed by date, use [Get voice usage](/en/api-reference/endpoints/get-voice-usage) instead. ## Endpoint ```http theme={"dark"} GET https://supertoneapi.com/v1/usage ``` ## Query parameters | Name | Required | Description | Example | | ----------------- | :------: | ---------------------------------------------------------------------------- | --------------------------- | | `start_time` | ✅ | RFC3339 start time. | `2025-05-01T00:00:00+00:00` | | `end_time` | ✅ | RFC3339 end time. | `2025-05-31T23:59:59+00:00` | | `bucket_width` | — | `hour` or `day`. Default `day`. | `day` | | `breakdown_type` | — | Array of breakdown dimensions: `voice_id`, `voice_name`, `api_key`, `model`. | `["voice_name"]` | | `page_size` | — | Items per page (1–20). Default `10`. | `10` | | `next_page_token` | — | Token from a previous response. | `eyJpZCI6IjEyMzQ1In0=` | ## Restrictions * `voice_id` and `voice_name` **cannot both** appear in `breakdown_type` in a single request. * If `start_time` and `end_time` have different UTC offsets, the offset on `end_time` is ignored — use matching offsets. * If `breakdown_type` is omitted, the response returns the total generated time per bucket (no per-dimension breakdown). ## See also Patterns for monitoring spend in production. Simpler per-voice rollup by date. ## OpenAPI ````yaml /openapi.json GET /v1/usage openapi: 3.0.0 info: title: Supertone Public API description: >- Supertone API is a RESTful API for using our state-of-the-art AI voice models. version: 0.9.6 contact: {} servers: - url: https://supertoneapi.com description: Production security: [] tags: - name: voices description: Voice Library API endpoints - name: custom_voices description: Custom Voice Management API endpoints - name: text_to_speech description: Text-to-Speech API endpoints - name: usage description: Usage Analytics API endpoints paths: /v1/usage: get: tags: - usage summary: Retrieve advanced API usage analytics description: >- Retrieves API usage data with advanced features including time bucketing, multi-dimensional breakdowns, and pagination. All timestamps should be in RFC3339 format. operationId: get_usage parameters: - name: start_time required: true in: query description: Start time in RFC3339 format schema: example: '2024-01-01T00:00:00+09:00' type: string - name: end_time required: true in: query description: End time in RFC3339 format schema: example: '2024-01-31T23:59:59+09:00' type: string - name: bucket_width required: false in: query description: Time bucket width for aggregation schema: default: day enum: - hour - day type: string - name: breakdown_type required: false in: query description: Dimensions to break down usage data schema: example: - voice_name type: array items: type: string enum: - voice_id - voice_name - api_key - model - name: page_size required: false in: query description: Number of results per page schema: minimum: 1 maximum: 20 default: 10 type: number - name: next_page_token required: false in: query description: Pagination token from previous response schema: type: string responses: '200': description: Usage analytics data successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/UsageAnalyticsResponse' '400': description: 'Bad Request: Invalid request parameters' content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: 'Unauthorized: Invalid API key' content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '408': description: 'Request Timeout: Processing took longer than 30 seconds' content: application/json: schema: $ref: '#/components/schemas/RequestTimeoutErrorResponse' '500': description: 'Internal Server Error: Failed to get usages' content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - api-key: [] components: schemas: UsageAnalyticsResponse: type: object properties: data: description: Array of time buckets containing usage data type: array items: $ref: '#/components/schemas/UsageBucket' next_page_token: type: string description: Pagination token for next page total: type: number description: Total number of time buckets across all pages required: - data - total BadRequestErrorResponse: type: object properties: status: type: string description: Response status example: error message: type: string description: Bad request error message example: Invalid request data required: - status - message UnauthorizedErrorResponse: type: object properties: status: type: string description: Response status example: error message: description: Unauthorized error details example: message: Invalid API Key error: Unauthorized statusCode: 401 allOf: - $ref: '#/components/schemas/ErrorMessageData' required: - status - message RequestTimeoutErrorResponse: type: object properties: status: type: string description: Response status example: error message: description: Request timeout error details example: message: Request timed out error: Request Timeout statusCode: 408 allOf: - $ref: '#/components/schemas/ErrorMessageData' required: - status - message InternalServerErrorResponse: type: object properties: status: type: string description: Response status example: error message: description: Internal server error details example: message: Failed to convert text to speech error: Internal Server Error statusCode: 500 allOf: - $ref: '#/components/schemas/ErrorMessageData' required: - status - message UsageBucket: type: object properties: starting_at: type: string description: RFC3339 timestamp for bucket start example: '2024-01-01T00:00:00+09:00' ending_at: type: string description: RFC3339 timestamp for bucket end example: '2024-01-01T01:00:00+09:00' results: description: Array of usage results within this time bucket type: array items: $ref: '#/components/schemas/UsageResult' required: - starting_at - ending_at - results ErrorMessageData: type: object properties: message: type: string description: Error message example: Invalid API Key error: type: string description: Error type example: Unauthorized status_code: type: number description: HTTP status code example: 401 required: - message - error - status_code UsageResult: type: object properties: voice_id: type: string description: Voice identifier voice_name: type: string description: Human-readable voice name api_key: type: string description: API key used model: type: string description: Model used minutes_used: type: number description: Total minutes of API usage required: - minutes_used securitySchemes: api-key: type: apiKey in: header name: x-sup-api-key ````