Skip to content
账户

Usage ​

查询当前 Key 的余额、额度、时间窗限额和用量统计。适合在脚本或客户端状态栏中展示剩余额度。

GET/v1/usage

查询参数 ​

daysinteger

返回最近多少天的每日用量,范围 1–90。超出范围返回 400。

start_datestring

模型统计的起始日期,格式 YYYY-MM-DD。默认 30 天前。

end_datestring

模型统计的结束日期(含当天),格式 YYYY-MM-DD。默认今天。

timezonestring

每日用量的时区,例如 Asia/Shanghai。

bash
curl "https://api.thetaio.tech/v1/usage?days=7" \
  -H "Authorization: Bearer $THETAIO_API_KEY"

响应模式 ​

响应的 mode 字段说明 Key 的计费方式:

mode条件关键字段
quota_limitedKey 设置了总额度或时间窗限额quota、rate_limits、expires_at
unrestrictedKey 没有独立限额,按钱包或订阅扣费planName、remaining、balance 或 subscription
json
{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": { "limit": 50, "used": 12.4, "remaining": 37.6, "unit": "USD" },
  "remaining": 37.6,
  "unit": "USD",
  "rate_limits": [
    {
      "window": "5h",
      "limit": 5,
      "used": 1.2,
      "remaining": 3.8,
      "window_start": "2026-11-19T04:00:00+08:00",
      "reset_at": "2026-11-19T09:00:00+08:00"
    }
  ],
  "expires_at": "2026-12-31T23:59:59+08:00",
  "days_until_expiry": 42
}
json
{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 86.2,
  "balance": 86.2,
  "unit": "USD"
}
json
{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "Pro 订阅",
  "remaining": 18.5,
  "unit": "USD",
  "subscription": {
    "daily_usage_usd": 1.5,
    "weekly_usage_usd": 6.2,
    "monthly_usage_usd": 21.0,
    "daily_limit_usd": 20,
    "weekly_limit_usd": 100,
    "monthly_limit_usd": 300,
    "expires_at": "2026-12-19T00:00:00+08:00"
  }
}

用量统计字段 ​

所有模式在有数据时还会返回:

字段说明
usage.today / usage.total今日与累计的请求数、输入 / 输出 / 缓存 Token、cost、actual_cost
daily_usage按 days 返回的每日用量
model_statsstart_date 至 end_date 内按模型汇总的用量

这些统计是尽力而为的:统计服务不可用时字段会缺省,不影响额度字段的返回。额度耗尽或已过期的 Key 仍可调用此接口。