> ## 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 > **Returns usage history by period.** **Advanced API usage** with support for time bucketing, multi-dimensional breakdowns, and pagination. ### Endpoint ```http theme={"dark"} https://supertoneapi.com/v1/usage ``` ### Notes * `voice_id` and `voice_name` cannot be set as `breakdown_type` values in the same request. * If no `breakdown_type` is specified, the response returns the total generated time for each time bucket. * If the UTC offset values differ between `start_time` and `end_time`, the value set in `end_time` will be ignored. ### Request Parameters | Name | Required | Description | Example | | ----------------- | -------- | ------------------------------------------------------------------------------------------ | --------------------------- | | `start_time` | Yes | Start time in RFC3339 format. | `2024-01-01T00:00:00+09:00` | | `end_time` | Yes | End time in RFC3339 format. | `2024-01-31T23:59:59+09:00` | | `bucket_width` | No | Time bucket width for aggregation. Default: `day`. Possible values: `hour`, `day`. | `day` | | `breakdown_type` | No | Dimensions to break down usage data. Possible values: `voice_id`, `voice_name`, `api_key`. | `["voice_name"]` | | `page_size` | No | Number of results per page (1–20). Default: `10`. | `10` | | `next_page_token` | No | Pagination token from the previous response. | `opaque_token` | ## 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.0 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 ````