Usage Statistics API

Retrieve usage statistics for your account, including per-model breakdown, daily usage, and summary totals.

Note: Query time range cannot exceed 31 days.

API Information

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

Request


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

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	Filter by specific model

Response

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

Field	Type	Description
data.per_model_usage	array	Usage statistics grouped by model
data.daily_usage	array	Usage statistics grouped by day
data.summary	object	Overall usage summary

per_model_usage

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	`0.488`
total_cost	float64	Total cost in USD	`130.000`
total_count	int64	Total number of invocations	`2660`
last_used_date	string	Last used date (`YYYY-MM-DD`)	`"2025-10-12"`

daily_usage

Field	Type	Description	Example
date	string	Date (`YYYY-MM-DD`)	`"2025-10-01"`
amount	float64	Total cost for the day in USD	`242.300`
count	int64	Total invocations for the day	`8095`
models	array	Per-model breakdown for the day	See below

models (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	`130.000`
count	int64	Invocations for this model on the day	`2660`

summary

Field	Type	Description	Example
total_cost	float64	Total cost in USD	`2423.000`
total_requests	int64	Total number of requests	`98765`
success_requests	int64	Number of successful requests	`95432`

Response Example

{
  "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
          }
        ]
      },
      {
        "date": "2025-10-02",
        "amount": 198.500,
        "count": 6543,
        "models": [
          {
            "model_uuid": "kwaivgi/kling-v2.0-i2v-master",
            "amount": 98.500,
            "count": 2015
          }
        ]
      }
    ],
    "summary": {
      "total_cost": 2423.000,
      "total_requests": 98765,
      "success_requests": 95432
    }
  }
}

Error Responses

Code	Message	Description
400	`invalid time range: end_time must be after start_time`	Invalid time range
400	`time range cannot exceed 31 days`	Query exceeds 31-day limit
401	`access_key is required`	Missing or invalid API key
500	`failed to get model usage summary`	Server error

Business Rules

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
Amount Precision: All amounts are rounded to 3 decimal places
Currency Unit: US Dollars (USD)
Sorting:
- per_model_usage: Sorted by last used date (descending)
- daily_usage: Sorted by date (ascending)
- models: Sorted by amount (descending)

Filtering

model_uuid Filter: When 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

Best Practices

Use appropriate time ranges (e.g., 7 days, 30 days) to avoid excessive data retrieval
Use model_uuid parameter when querying specific model data to reduce result set size
Consider implementing client-side caching for frequently accessed data

Use Cases

View Overall Usage

View usage statistics for all models within 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"
  }'

View Specific Model Usage

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"
  }'

View Last 7 Days Usage

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"
  }'

Overview