> ## 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

> ボイス、API キー、モデル別の内訳とともに、バケット集計された使用量分析を返します。ダッシュボードやレポートに最適です。

<Note>
  このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/api-reference/endpoints/get-usage)もあわせてご確認ください。
</Note>

生成オーディオの分数を時間バケットに集計し、必要に応じてボイス、API キー、モデル別に内訳化して返します。ダッシュボード、社内レポート、キー別の課金按分などにご利用ください。

日付ごとのシンプルなボイス単位の集計が必要な場合は、代わりに [ボイス使用量取得](/ja/api-reference/endpoints/get-voice-usage) をご利用ください。

## エンドポイント

```http theme={"dark"}
GET https://supertoneapi.com/v1/usage
```

## クエリパラメータ

| Name              | Required | Description                                              | Example                     |
| ----------------- | :------: | -------------------------------------------------------- | --------------------------- |
| `start_time`      |     ✅    | RFC3339 形式の開始時刻です。                                       | `2025-05-01T00:00:00+00:00` |
| `end_time`        |     ✅    | RFC3339 形式の終了時刻です。                                       | `2025-05-31T23:59:59+00:00` |
| `bucket_width`    |     —    | `hour` または `day`。デフォルトは `day`。                           | `day`                       |
| `breakdown_type`  |     —    | 内訳ディメンションの配列: `voice_id`、`voice_name`、`api_key`、`model`。 | `["voice_name"]`            |
| `page_size`       |     —    | 1 ページあたりの件数（1〜20）です。デフォルト `10`。                          | `10`                        |
| `next_page_token` |     —    | 前回のレスポンスから取得したトークンです。                                    | `eyJpZCI6IjEyMzQ1In0=`      |

## 制約事項

* `voice_id` と `voice_name` を **同時に** `breakdown_type` に指定することはできません。
* `start_time` と `end_time` の UTC オフセットが異なる場合、`end_time` のオフセットは無視されます。両者で一致するオフセットをご使用ください。
* `breakdown_type` を省略すると、レスポンスはバケットごとの合計生成時間のみを返します（ディメンション別の内訳は含まれません）。

## 関連項目

<CardGroup cols={2}>
  <Card title="Docs: Cost and usage" icon="credit-card" href="/ja/docs/production/cost-and-usage">
    本番環境でのコスト監視パターン。
  </Card>

  <Card title="Get voice usage" icon="microphone" href="/ja/api-reference/endpoints/get-voice-usage">
    日付別のシンプルなボイス単位の集計。
  </Card>
</CardGroup>


## 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

````