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. Missing time boundaries are filled automatically:
end_timedefaults to now, andstart_timedefaults to 24 hours beforeend_time. Usage reports are refreshed periodically, so the most recent activity may not appear immediately.
Endpoint
POST https://api.wavespeed.ai/api/v3/user/usage_statsTeam organizations: This endpoint requires a key created by a current Owner, Admin, or Billing member. It returns organization-wide usage rather than usage scoped to the calling key. Developer keys can read the organization balance but cannot use this endpoint. These role restrictions do not apply to personal organizations.
Request
curl --fail-with-body --connect-timeout 10 --max-time 60 --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 | No | Start time in ISO 8601 format. Defaults to 24 hours before end_time |
end_time | string | No | End time in ISO 8601 format. Defaults to the current time |
model_uuid | string | No | Filter by specific model |
Response
{
"code": 200,
"message": "success",
"data": {
"per_model_usage": [
{
"model_uuid": "pixverse/pixverse-v5.5/image-to-video",
"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": "pixverse/pixverse-v5.5/image-to-video",
"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["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,
timeout=(10, 60),
)
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
raise RuntimeError(body.get("message", "Failed to retrieve usage"))
return body["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 --fail-with-body --connect-timeout 10 --max-time 60 --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": "pixverse/pixverse-v5.5/image-to-video"
}'Error Responses
| Code | Message | Description |
|---|---|---|
| 400 | The usage time range is invalid. end_time must be after start_time. | Invalid time range |
| 400 | The selected time range is too large. Please choose a range of 31 days or fewer. | Query exceeds 31-day limit |
| 401 | Missing API key. Send it as: Authorization: Bearer <your API key>. | Missing API key; an invalid or inactive key returns a corresponding authentication error |
| 403 | Forbidden | The key creator’s current role cannot use API keys, or the key does not have access to this endpoint |