How to Check Usage
Retrieve usage statistics for your account, including per-model breakdown, daily usage, and summary totals.
Note: Query time range cannot exceed 31 days.
Endpoint
POST https://api.wavespeed.ai/api/v3/user/usage_statsRequest
curl --location --request POST 'https://api.wavespeed.ai/api/v3/user/usage_stats' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"start_time": "2025-10-01T00:00:00Z",
"end_time": "2025-10-12T23:59:59Z"
}'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": [
{
"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"
}
],
"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
}
]
}
],
"summary": {
"total_cost": 2423.000,
"total_requests": 98765,
"success_requests": 95432
}
}
}Response Fields
| 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 |
|---|---|---|
model_uuid | string | Model UUID identifier |
model_type | string | Model type |
unit_price | float | Unit price in USD |
total_cost | float | Total cost in USD |
total_count | integer | Total number of invocations |
last_used_date | string | Last used date (YYYY-MM-DD) |
daily_usage
| Field | Type | Description |
|---|---|---|
date | string | Date (YYYY-MM-DD) |
amount | float | Total cost for the day in USD |
count | integer | Total invocations for the day |
models | array | Per-model breakdown for the day |
summary
| Field | Type | Description |
|---|---|---|
total_cost | float | Total cost in USD |
total_requests | integer | Total number of requests |
success_requests | integer | Number of successful requests |
Python Example
import os
import requests
api_key = os.environ.get("WAVESPEED_API_KEY")
def get_usage(start_time, end_time, model_uuid=None):
payload = {
"start_time": start_time,
"end_time": end_time
}
if model_uuid:
payload["model_uuid"] = model_uuid
response = requests.post(
"https://api.wavespeed.ai/api/v3/user/usage_stats",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
},
json=payload
)
return response.json()["data"]
# Get usage for a time range
usage = get_usage("2025-10-01T00:00:00Z", "2025-10-12T23:59:59Z")
print(f"Total cost: ${usage['summary']['total_cost']}")
print(f"Total requests: {usage['summary']['total_requests']}")
# Show top models
for model in usage["per_model_usage"][:5]:
print(f"- {model['model_uuid']}: {model['total_count']} requests, ${model['total_cost']}")Filter by Model
curl --location --request POST 'https://api.wavespeed.ai/api/v3/user/usage_stats' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"start_time": "2025-10-01T00:00:00Z",
"end_time": "2025-10-12T23:59:59Z",
"model_uuid": "kwaivgi/kling-v2.0-i2v-master"
}'Error Responses
| Code | Message | Description |
|---|---|---|
| 400 | invalid time range | end_time must be after start_time |
| 400 | time range cannot exceed 31 days | Query exceeds 31-day limit |
| 401 | access_key is required | Missing or invalid API key |