User Usage Statistics API Documentation

Overview

This API retrieves usage statistics for models within an organization, including aggregated statistics by model, daily statistics, and overall usage summary.

API Information

Item	Description
API Name	Get User Usage Statistics
API Path	`/api/v3/user/usage_stats`
HTTP Method	`POST`
Content-Type	`application/json`
Authentication	Bearer Token via `Authorization` header

Request Parameters

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Access Key in format: `Bearer {access_key}`

Body Parameters

Parameter	Type	Required	Description
start_time	string	Yes	Start time in ISO 8601 format, e.g., `2025-10-01T00:00:00Z`
end_time	string	Yes	End time in ISO 8601 format, e.g., `2025-10-12T23:59:59Z`
model_uuid	string	No	Model UUID for filtering specific model usage

Request Example

{
  "start_time": "2025-10-01T00:00:00Z",
  "end_time": "2025-10-12T23:59:59Z"
}

Response Parameters

Response Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "per_model_usage": [...],
    "daily_usage": [...],
    "summary": {...}
  }
}

Response Field Descriptions

Root Fields

Field	Type	Description
code	int	Response status code, 200 indicates success
message	string	Response message
data	object	Statistics data object

data Object

Field	Type	Description
per_model_usage	array	Array of aggregated usage statistics by model
daily_usage	array	Array of daily usage statistics
summary	object	Overall usage summary

per_model_usage Array Elements

Field	Type	Description	Example
model_uuid	string	Model UUID identifier	`"kwaivgi/kling-v2.0-i2v-master"`
model_type	string	Model type	`"text-to-video"`
unit_price	float64	Unit price in USD, rounded to 3 decimal places	`0.488`
total_cost	float64	Total cost in USD, rounded to 3 decimal places	`130.000`
total_count	int64	Total number of invocations	`2660`
last_used_date	string	Last used date in format `YYYY-MM-DD`	`"2025-10-12"`

daily_usage Array Elements

Field	Type	Description	Example
date	string	Date in format `YYYY-MM-DD`	`"2025-10-01"`
amount	float64	Total cost for the day in USD, rounded to 3 decimal places	`242.300`
count	int64	Total number of invocations for the day	`8095`
models	array	Array of model usage details for the day	See below

models Array Elements (under daily_usage)

Field	Type	Description	Example
model_uuid	string	Model UUID identifier	`"kwaivgi/kling-v2.0-i2v-master"`
amount	float64	Cost for this model on the day in USD, rounded to 3 decimal places	`130.000`
count	int64	Number of invocations for this model on the day	`2660`

summary Object

Field	Type	Description	Example
total_cost	float64	Total cost within the time range in USD, rounded to 3 decimal places	`2423.000`
total_requests	int64	Total number of requests	`98765`
success_requests	int64	Number of successful requests	`95432`

Response Examples

Success Response

{
  "code": 200,
  "message": "success",
  "data": {
    "per_model_usage": [
      {
        "model_uuid": "kwaivgi/kling-v2.0-i2v-master",
        "model_type": "text-to-video",
        "unit_price": 0.488,
        "total_cost": 1300.000,
        "total_count": 2660,
        "last_used_date": "2025-10-12"
      },
      {
        "model_uuid": "kwaivgi/kling-v2.1-i2v-pro",
        "model_type": "text-to-video",
        "unit_price": 0.976,
        "total_cost": 450.000,
        "total_count": 461,
        "last_used_date": "2025-10-11"
      }
    ],
    "daily_usage": [
      {
        "date": "2025-10-01",
        "amount": 242.300,
        "count": 8095,
        "models": [
          {
            "model_uuid": "kwaivgi/kling-v2.0-i2v-master",
            "amount": 130.000,
            "count": 2660
          },
          {
            "model_uuid": "kwaivgi/kling-v2.1-i2v-pro",
            "amount": 45.000,
            "count": 450
          },
          {
            "model_uuid": "wavespeed-ai/wan-2.1/t2v-720p-lora",
            "amount": 30.000,
            "count": 300
          }
        ]
      },
      {
        "date": "2025-10-02",
        "amount": 198.500,
        "count": 6543,
        "models": [
          {
            "model_uuid": "kwaivgi/kling-v2.0-i2v-master",
            "amount": 98.500,
            "count": 2015
          },
          {
            "model_uuid": "kwaivgi/kling-v2.1-i2v-pro",
            "amount": 55.000,
            "count": 564
          }
        ]
      }
    ],
    "summary": {
      "total_cost": 2423.000,
      "total_requests": 98765,
      "success_requests": 95432
    }
  }
}

Error Responses

401 - Unauthorized

{
  "code": 401,
  "message": "access_key is required"
}

Description: Access Key is not provided or invalid.

400 - Invalid Parameters

{
  "code": 400,
  "message": "invalid time range: end_time must be after start_time"
}

Description: Request parameters do not meet requirements, such as invalid time range.

400 - Time Range Exceeded

{
  "code": 400,
  "message": "time range cannot exceed 31 days"
}

Description: The query time range exceeds the 31-day limit.

500 - Server Error

{
  "code": 500,
  "message": "failed to get model usage summary: ..."
}

Description: Internal server error occurred.

Business Rules and Limitations

Time Range Restrictions

Required Fields: Both start_time and end_time must be provided
Maximum Time Range: Cannot exceed 31 days
Time Validity: end_time must be later than start_time
Date Format: ISO 8601 standard format (e.g., 2025-10-01T00:00:00Z)

Data Statistics Rules

Statistics Dimension: Statistics are aggregated by day (stat_date)
Amount Precision: All amounts are rounded to 3 decimal places using standard rounding
Currency Unit: US Dollars (USD)
Sorting Rules:
- per_model_usage: Sorted by last used date in descending order
- daily_usage: Sorted by date in ascending order
- models (under daily_usage): Sorted by amount in descending order

Filtering Functionality

model_uuid Filter: When the model_uuid parameter is provided, all statistics (including summary) will only include data for that specific model
Exact Match: model_uuid uses exact matching, fuzzy queries are not supported

Authentication and Authorization

Authentication Method: Authentication via Access Key

Use Cases

Use Case 1: View Overall Usage

Purpose: View usage statistics for all models within an organization over a specific time period.

curl -X POST "https://api.wavespeed.ai/api/v3/user/usage_stats" \
  -H "Authorization: Bearer your_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-10-01T00:00:00Z",
    "end_time": "2025-10-12T23:59:59Z"
  }'

Use Case 2: View Specific Model Usage

Purpose: View usage statistics for a specific model only.

curl -X POST "https://api.wavespeed.ai/api/v3/user/usage_stats" \
  -H "Authorization: Bearer your_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-10-01T00:00:00Z",
    "end_time": "2025-10-12T23:59:59Z",
    "model_uuid": "kwaivgi/kling-v2.0-i2v-master"
  }'

Use Case 3: View Last 7 Days Usage

Purpose: Quickly view recent usage trends.

curl -X POST "https://api.wavespeed.ai/api/v3/user/usage_stats" \
  -H "Authorization: Bearer your_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-10-06T00:00:00Z",
    "end_time": "2025-10-12T23:59:59Z"
  }'

Data Specifications

Amount Calculation

Results are rounded to 3 decimal places using standard rounding

Invocation Count Statistics

completed_count: Successfully completed request counts
count (in daily_usage and models): Successfully

Best Practices

Reasonable Time Ranges: Use appropriate time ranges (e.g., 7 days, 30 days) to avoid excessive data retrieval
Model Filtering: Use model_uuid parameter when querying specific model data to reduce result set size
Caching: Consider implementing client-side caching for frequently accessed data
Rate Limiting: Be mindful of API rate limits when making frequent requests

Predictions Billings