openapi: 3.2.0
info:
  title: ElevenLabs API Documentation Usage API
  description: This is the documentation for the ElevenLabs API. You can use this API to use our service programmatically, this is done by using your API key. You can find your API key in the dashboard at https://elevenlabs.io/app/settings/api-keys.
  version: '1.0'
tags:
- name: Usage
paths:
  /v1/usage/character-stats:
    get:
      summary: Get Characters Usage Metrics (Deprecated)
      description: '(Deprecated) This endpoint is deprecated. Use /v1/workspace/analytics/query/usage-by-product-over-time instead, which exposes the bucket size as `interval_seconds` (an integer in seconds) rather than `aggregation_interval`. Returns the usage metrics for the current user or the entire workspace they are part of. The response provides a time axis based on the specified aggregation interval (default: day), with usage values for each interval along that axis. Usage is broken down by the selected breakdown type. For example, breakdown type "voice" will return the usage of each voice for each interval along the time axis.'
      operationId: usage_characters
      deprecated: true
      parameters:
      - name: start_unix
        in: query
        required: true
        schema:
          type: integer
          description: UTC Unix timestamp for the start of the usage window, in milliseconds. To include the first day of the window, the timestamp should be at 00:00:00 of that day.
          examples:
          - '1685574000'
          title: Start Unix
        description: UTC Unix timestamp for the start of the usage window, in milliseconds. To include the first day of the window, the timestamp should be at 00:00:00 of that day.
      - name: end_unix
        in: query
        required: true
        schema:
          type: integer
          description: UTC Unix timestamp for the end of the usage window, in milliseconds. To include the last day of the window, the timestamp should be at 23:59:59 of that day.
          examples:
          - '1688165999'
          title: End Unix
        description: UTC Unix timestamp for the end of the usage window, in milliseconds. To include the last day of the window, the timestamp should be at 23:59:59 of that day.
      - name: include_workspace_metrics
        in: query
        required: false
        schema:
          type: boolean
          description: Whether or not to include the statistics of the entire workspace.
          default: false
          title: Include Workspace Metrics
        description: Whether or not to include the statistics of the entire workspace.
      - name: breakdown_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/BreakdownTypes'
          description: How to break down the information. Cannot be "user" if include_workspace_metrics is False.
          default: none
        description: How to break down the information. Cannot be "user" if include_workspace_metrics is False.
      - name: aggregation_interval
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/UsageAggregationInterval'
          description: How to aggregate usage data over time. Can be "hour", "day", "week", "month", or "cumulative".
          default: day
        description: How to aggregate usage data over time. Can be "hour", "day", "week", "month", or "cumulative".
      - name: aggregation_bucket_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Aggregation bucket size in seconds. Overrides the aggregation interval.
          title: Aggregation Bucket Size
        description: Aggregation bucket size in seconds. Overrides the aggregation interval.
      - name: metric
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/MetricType'
          description: Which metric to aggregate.
          default: credits
        description: Which metric to aggregate.
      - name: xi-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
          title: Xi-Api-Key
        description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageCharactersResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name: usage
      x-fern-sdk-method-name: get
      tags:
      - Usage
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MetricType:
      type: string
      enum:
      - credits
      - tts_characters
      - minutes_used
      - request_count
      - ttfb_avg
      - ttfb_p95
      - fiat_units_spent
      - concurrency
      - concurrency_average
      title: MetricType
    BreakdownTypes:
      type: string
      enum:
      - none
      - voice
      - voice_multiplier
      - user
      - groups
      - api_keys
      - all_api_keys
      - product_type
      - model
      - resource
      - request_queue
      - region
      - subresource_id
      - reporting_workspace_id
      - has_api_key
      - request_source
      title: BreakdownTypes
      description: How to break down the information. Cannot be "user" or "api_key" if include_workspace_metrics is False.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UsageCharactersResponseModel:
      properties:
        time:
          items:
            type: integer
          type: array
          title: Time
          description: The time axis with unix timestamps for each day.
        usage:
          additionalProperties:
            items:
              type: number
            type: array
          type: object
          title: Usage
          description: The usage of each breakdown type along the time axis.
      type: object
      required:
      - time
      - usage
      title: UsageCharactersResponseModel
      example:
        time:
        - 1738252091000
        - 1739404800000
        usage:
          All:
          - 49
          - 1053
    UsageAggregationInterval:
      type: string
      enum:
      - hour
      - day
      - week
      - month
      - cumulative
      title: UsageAggregationInterval
      description: The time interval over which to aggregate the usage data.