Billing Report

Query the authenticated API key’s actual spend for a date range, grouped by billed model, including cost components, token counts, and request counts.

Endpoint

GET https://hao.ai/api/v1/usage/billing-report

Send requests to the website host hao.ai.

Authentication

Pass an API key created in the dashboard in the request header:

Authorization: Bearer sk-haoai-...

Existing sk-pohu-... keys are also accepted. A positive wallet balance is not required. The key must be enabled and unexpired. If it has an IP allowlist, the script’s outbound IP must match that list.

Query Parameters

Send parameters in the query string. For daily billing, use start_date, end_date, and timezone.

Supported presets: 12h, 24h, 48h, today, yesterday, 2daysago, 3d, 7d, 14d, 30d, 90d, thismonth, lastmonth, and custom. This report uses calendar windows: 12h and 24h mean today, and 48h includes yesterday and today. Prefer explicit dates or yesterday. An explicit date pair takes precedence; avoid mixing range formats.

A query window cannot exceed 90 days and returns only the authenticated API key’s costs. Unknown or duplicate query parameters return 400.

Daily Spend by Model

Set start_date and end_date to the same date to get each model’s actual_cost for that day. For multiple days, query each date separately. A multi-day request aggregates the entire window; granularity and group_by are not supported.

For example, 2026-10-05 with Asia/Shanghai covers midnight on October 5 through midnight on October 6 in that timezone. The response expresses the window in UTC with an exclusive end time.

Request Examples

curl --get 'https://hao.ai/api/v1/usage/billing-report' \
  -H "Authorization: Bearer $HAOAI_API_KEY" \
  --data-urlencode 'start_date=2026-10-05' \
  --data-urlencode 'end_date=2026-10-05' \
  --data-urlencode 'timezone=Asia/Shanghai'

import os
from decimal import Decimal
 
import requests
 
resp = requests.get(
    "https://hao.ai/api/v1/usage/billing-report",
    headers={"Authorization": f"Bearer {os.environ['HAOAI_API_KEY']}"},
    params={
        "start_date": "2026-10-05",
        "end_date": "2026-10-05",
        "timezone": "Asia/Shanghai",
    },
    timeout=10,
)
resp.raise_for_status()
report = resp.json(parse_float=Decimal)["data"]
for row in report["rows"]:
    print(f"{row['model']}: ${row['actual_cost']:.6f}")
print(f"Total: ${report['totals']['actual_cost']:.6f}")

const params = new URLSearchParams({
  start_date: '2026-10-05',
  end_date: '2026-10-05',
  timezone: 'Asia/Shanghai',
})
const resp = await fetch(`https://hao.ai/api/v1/usage/billing-report?${params}`, {
  headers: { Authorization: `Bearer ${process.env.HAOAI_API_KEY}` },
  signal: AbortSignal.timeout(10_000),
})
if (!resp.ok) {
  throw new Error(`Billing report failed: HTTP ${resp.status}`)
}
const { data: report } = await resp.json()
for (const row of report.rows) {
  console.log(`${row.model}: $${row.actual_cost.toFixed(6)}`)
}
console.log(`Total: $${report.totals.actual_cost.toFixed(6)}`)

Response Format

Successful response, 200 OK:

{
  "code": 0,
  "message": "success",
  "data": {
    "currency": "USD",
    "range": {
      "from": "2026-10-04T16:00:00Z",
      "to": "2026-10-05T16:00:00Z"
    },
    "rows": [
      {
        "api_key_id": "63a7f4c1-1542-4a65-a03e-4d0e15f71962",
        "api_key_name": "Production",
        "api_key_prefix": "sk-haoai-7fA3k9mB",
        "api_key_suffix": "hJv2",
        "model": "anthropic/claude-sonnet-4-5",
        "requests": 18,
        "input_tokens": 120000,
        "output_tokens": 45000,
        "cache_read_tokens": 12000,
        "cache_creation_tokens": 3000,
        "input_cost": 0.4,
        "output_cost": 0.8,
        "cache_read_cost": 0.1,
        "cache_creation_cost": 0.5,
        "search_cost": 0,
        "image_cost": 0,
        "video_cost": 0,
        "other_cost": 0,
        "actual_cost": 1.8,
        "official_cost": 3,
        "effective_discount": 0.6
      }
    ],
    "totals": {
      "requests": 18,
      "input_tokens": 120000,
      "output_tokens": 45000,
      "cache_read_tokens": 12000,
      "cache_creation_tokens": 3000,
      "input_cost": 0.4,
      "output_cost": 0.8,
      "cache_read_cost": 0.1,
      "cache_creation_cost": 0.5,
      "search_cost": 0,
      "image_cost": 0,
      "video_cost": 0,
      "other_cost": 0,
      "actual_cost": 1.8,
      "official_cost": 3,
      "effective_discount": 0.6
    }
  }
}

Envelope and Report Fields

rows[] Fields

totals contains the same count and cost fields, without key, channel, or model identifiers.

The report uses the same processed usage aggregates as the dashboard. Recently completed requests may appear after a delay; query again later if needed. A failed query returns an error, never a fabricated zero-cost result. Recent calendar-day windows in whole-hour timezones can be represented exactly. Beyond the 100-day hourly retention window, historical ranges must align with whole UTC days. Windows that cannot be represented exactly by retained aggregates return 400.

Rate Limits

A maximum of 3 requests per minute is allowed. Excessive requests return 429.

Send requests sequentially, at least 20 seconds apart. On 429, wait for Retry-After before retrying. Responses include Cache-Control: no-store and must not be stored in a public cache.

Error Responses

Example error response:

{
  "code": 429,
  "message": "too many requests",
  "reason": "rate_limited"
}