How to Check Billings

Search billing records with optional filters such as billing type, prediction UUIDs, sort order, and time range. Returns paginated results.

Very recent billing activity may take a short time to appear. If you are checking a request that just finished, retry the search after a brief delay.

Endpoint

POST https://api.wavespeed.ai/api/v3/billings/search

Request

curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/billings/search' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "page": 1,
    "page_size": 10
}'

Parameters

Parameter	Type	Required	Default	Description
`billing_type`	string	No	-	Filter by billing type (e.g., `deduct`)
`prediction_uuids`	array	No	-	Filter by one or more related prediction UUIDs
`sort`	string	No	-	Sort order: `created_at ASC` or `created_at DESC`
`start_time`	string	No	-	Start of time range (milliseconds since Unix epoch)
`end_time`	string	No	-	End of time range (milliseconds since Unix epoch)
`access_key_uuid`	string	No	-	Filter by the public UUID of an access key
`model_uuid`	string	No	-	Filter by model ID, such as `wavespeed-ai/z-image/turbo`
`page`	integer	Yes	1	Page number (>=1)
`page_size`	integer	Yes	10	Items per page (1-100)

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "total": 5,
    "items": [
      {
        "uuid": "1113382d696d4677a036540a9bbb88b4",
        "access_key_uuid": "6f8cfbf889fa4fbf88960e938c1b0d13",
        "access_key_name": "aboy",
        "billing_type": "deduct",
        "price": 0.04,
        "created_at": "2026-04-23T12:23:30.933Z",
        "updated_at": "2026-04-23T12:23:30.933Z",
        "order": {
          "uuid": "ca1224af40134dada3943d1ed8e3404b",
          "state": "pre",
          "price": 0.04,
          "origin_price": 0.04,
          "status": ""
        },
        "prediction": {
          "uuid": "0cbf014f272a461faab2d19929ccf759",
          "model_uuid": "bytedance/seedream-v4.5",
          "status": "created"
        }
      }
    ]
  }
}

Response Fields

Field	Type	Description
`data.page`	integer	Current page number
`data.total`	integer	Total number of records
`data.items`	array	Array of billing records

Billing Record Object

Field	Type	Description
`uuid`	string	Billing record UUID
`access_key_uuid`	string	Public UUID of the access key used
`access_key_name`	string	Name of the access key used
`billing_type`	string	Type of billing (e.g., `deduct`)
`price`	float	Amount in USD
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)
`order`	object	Related order information
`prediction`	object	Related prediction information

Python Example

import os
import requests
 
api_key = os.environ["WAVESPEED_API_KEY"]
 
def get_billings(page=1, page_size=10, billing_type=None):
    payload = {
        "page": page,
        "page_size": page_size
    }
    if billing_type:
        payload["billing_type"] = billing_type
 
    response = requests.post(
        "https://api.wavespeed.ai/api/v3/billings/search",
        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 list billings"))
    return body["data"]
 
# Get recent billings
billings = get_billings()
 
print(f"Total records: {billings['total']}")
for item in billings["items"]:
    print(f"{item['created_at']}: ${item['price']} ({item['billing_type']})")

Filter by Type

curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/billings/search' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "billing_type": "deduct",
    "page": 1,
    "page_size": 10
}'

Filter by Time Range

curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/billings/search' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "start_time": "1759317210051",
    "end_time": "1759317227408",
    "sort": "created_at DESC",
    "page": 1,
    "page_size": 10
}'

Filter by Prediction

curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/billings/search' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "prediction_uuids": ["cb54bb552ff94e1ea6a5c2976fe1c0c1"],
    "page": 1,
    "page_size": 10
}'

Check Balance Check Usage