How to Export Billings

How to Export Billings

Export billing records for your organization. Supports both synchronous query (JSON response) and asynchronous export (CSV file download).

Sync Query API

Query billing records with pagination. Returns JSON response directly. Limited to 100,000 records.

Endpoint

POST https://api.wavespeed.ai/api/v3/scheduler/billings/query

Request

curl -X POST "https://api.wavespeed.ai/api/v3/scheduler/billings/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year_month": "2025-01",
    "page": 1,
    "page_size": 100
  }'

Parameters

ParameterTypeRequiredDescription
year_monthstringYesBilling month in format YYYY-MM (e.g., “2025-01”)
pageintegerNoPage number, default 1
page_sizeintegerNoRecords per page, default 100, max 1000

Note: Organization is automatically determined from your API key.

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "total": 515,
    "items": [
      {
        "uuid": "fdb619395f9247a8b7b973527ec7f687",
        "billing_type": "deduct",
        "price": -0.25,
        "created_at": "2025-01-02T09:18:42.663Z",
        "updated_at": "2025-01-02T09:18:42.663Z",
        "access_key_name": "my-api-key",
        "prediction": {
          "uuid": "fd4924a6c8cb4b3f95f72ccd58e610b5",
          "model_uuid": "wavespeed-ai/flux-dev",
          "status": "completed"
        }
      }
    ]
  }
}

Response Fields

FieldTypeDescription
pageintegerCurrent page number
totalintegerTotal number of records
itemsarrayArray of billing records
items[].uuidstringBilling record UUID
items[].billing_typestringType: “deduct” or “refund”
items[].pricenumberAmount in USD (negative for deduct, positive for refund)
items[].created_atstringCreation timestamp (ISO 8601)
items[].access_key_namestringName of the access key used
items[].predictionobjectAssociated prediction information

Python Example

import requests
 
response = requests.post(
    "https://api.wavespeed.ai/api/v3/scheduler/billings/query",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "year_month": "2025-01",
        "page": 1,
        "page_size": 100
    }
)
 
data = response.json()
print(f"Total records: {data['data']['total']}")
for item in data['data']['items']:
    print(f"{item['prediction']['uuid']}: ${item['price']}")

JavaScript Example

const response = await fetch("https://api.wavespeed.ai/api/v3/scheduler/billings/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    year_month: "2025-01",
    page: 1,
    page_size: 100
  })
});
 
const data = await response.json();
console.log(`Total records: ${data.data.total}`);

Async Export API

Export large billing datasets as CSV files. Recommended for datasets exceeding 100,000 records.

Step 1: Create Export Task

Endpoint

POST https://api.wavespeed.ai/api/v3/scheduler/billings/export

Request

curl -X POST "https://api.wavespeed.ai/api/v3/scheduler/billings/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year_month": "2025-01"
  }'

Parameters

ParameterTypeRequiredDescription
year_monthstringYesBilling month in format YYYY-MM (e.g., “2025-01”)

Note: Organization is automatically determined from your API key.

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "26dd31a2-4b8e-4c41-87c2-2da871a99a05",
    "status": "pending",
    "total_count": 13838450,
    "message": "Export task created, please query status later"
  }
}

Step 2: Query Task Status

Endpoint

GET https://api.wavespeed.ai/api/v3/scheduler/billings/export/{task_id}

Request

curl -X GET "https://api.wavespeed.ai/api/v3/scheduler/billings/export/26dd31a2-4b8e-4c41-87c2-2da871a99a05" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Processing)

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "26dd31a2-4b8e-4c41-87c2-2da871a99a05",
    "status": "processing",
    "progress": 45,
    "total_count": 13838450,
    "created_at": "2025-01-09T02:06:02Z",
    "updated_at": "2025-01-09T02:10:15Z"
  }
}

Response (Completed)

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "26dd31a2-4b8e-4c41-87c2-2da871a99a05",
    "status": "completed",
    "progress": 100,
    "total_count": 13838450,
    "file_count": 139,
    "download_url": "https://cdn.wavespeed.ai/exports/billings/12345/2025-01.zip",
    "created_at": "2025-01-09T02:06:02Z",
    "updated_at": "2025-01-09T02:45:30Z"
  }
}

Task Status Response Fields

FieldTypeDescription
task_idstringUnique task identifier
statusstringTask status: “pending”, “processing”, “completed”, “failed”
progressintegerProgress percentage (0-100)
total_countintegerTotal number of records to export
file_countintegerNumber of CSV files generated (available when completed)
download_urlstringURL to download the ZIP file (available when completed)
messagestringError message (available when failed)
created_atstringTask creation timestamp
updated_atstringLast update timestamp

CSV File Format

The exported ZIP file contains CSV files with the following columns:

ColumnDescription
AccessKey NameName of the access key used
Prediction IDUUID of the prediction
ModelModel identifier (e.g., “wavespeed-ai/flux-dev”)
DateTimestamp of the billing record
Amount ($)Amount in USD (negative for charges, positive for refunds)

Python Example (Async Export)

import requests
import time
 
# Step 1: Create export task
response = requests.post(
    "https://api.wavespeed.ai/api/v3/scheduler/billings/export",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "year_month": "2025-01"
    }
)
 
task_id = response.json()['data']['task_id']
print(f"Task created: {task_id}")
 
# Step 2: Poll for completion
while True:
    status_response = requests.get(
        f"https://api.wavespeed.ai/api/v3/scheduler/billings/export/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
 
    data = status_response.json()['data']
    print(f"Status: {data['status']}, Progress: {data.get('progress', 0)}%")
 
    if data['status'] == 'completed':
        print(f"Download URL: {data['download_url']}")
        break
    elif data['status'] == 'failed':
        print(f"Export failed: {data.get('message')}")
        break
 
    time.sleep(10)  # Wait 10 seconds before next poll

JavaScript Example (Async Export)

// Step 1: Create export task
const createResponse = await fetch("https://api.wavespeed.ai/api/v3/scheduler/billings/export", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    year_month: "2025-01"
  })
});
 
const { data: { task_id } } = await createResponse.json();
console.log(`Task created: ${task_id}`);
 
// Step 2: Poll for completion
const pollStatus = async () => {
  const response = await fetch(
    `https://api.wavespeed.ai/api/v3/scheduler/billings/export/${task_id}`,
    { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
  );
 
  const { data } = await response.json();
  console.log(`Status: ${data.status}, Progress: ${data.progress || 0}%`);
 
  if (data.status === 'completed') {
    console.log(`Download URL: ${data.download_url}`);
    return data.download_url;
  } else if (data.status === 'failed') {
    throw new Error(`Export failed: ${data.message}`);
  }
 
  await new Promise(resolve => setTimeout(resolve, 10000));
  return pollStatus();
};
 
const downloadUrl = await pollStatus();

Error Responses

CodeDescription
400Invalid parameters (e.g., invalid year_month format)
401Invalid API key
404Task not found
500Internal server error

Limits

LimitValue
Sync query max page size1,000
CSV file max rows100,000 per file
Export file retention7 days

Notes

  • Use pagination to query large datasets (max 1,000 records per page).
  • For bulk download, use the async export API to get CSV files.
  • Exported files are automatically compressed as ZIP archives.
  • Files are retained for 7 days and then automatically deleted.
  • Historical data (previous quarters) is retrieved from archive database.

Related Pages

Account Levels & Rate LimitsRefund Policy
© 2025 WaveSpeedAI. All rights reserved.