GET https://ollama.com/api/usage 返回云端推理、联网搜索、网页抓取的用量统计。这是唯一能查到「花了多少钱」的接口。

版本基线 v0.40.12，官方 docs.ollama.com/api/cloud-usage。

一、调用

curl 'https://ollama.com/api/usage?range=24h' \
  -H "Authorization: Bearer $OLLAMA_API_KEY"

返回：

{
  "range": "24h",
  "scope": "self",
  "granularity": "hour",
  "from": "2026-09-30T02:00:00Z",
  "until": "2026-10-01T02:30:00Z",
  "totals": {
    "request_count": 15,
    "usage_usd": 0.01718,
    "input_tokens": 106000,
    "cached_input_tokens": 46000,
    "output_tokens": 13600
  },
  "buckets": [
    {
      "from": "2026-09-30T12:00:00Z",
      "until": "2026-09-30T13:00:00Z",
      "request_count": 4,
      "usage_usd": 0.0052,
      "input_tokens": 24000,
      "cached_input_tokens": 0,
      "output_tokens": 3200
    }
  ]
}

二、查询参数

参数	取值	默认	说明
range	24h / 7d / 30d	7d	统计窗口
scope	self / team	self	个人或团队
group_by	model	—	按模型分组

不支持自定义时间范围，也不能传重复参数——不合法的组合直接返回 400。

三、三个时间窗口的含义

范围	起点	分桶	桶数
24h	当前 UTC 小时开始前 24 小时	小时	25
7d	七天前 00:00 UTC	天	8
30d	三十天前 00:00 UTC	天	31

规则细节：

• 每个范围都在请求时刻结束
• 最后一个桶覆盖当前小时/天，带 partial: true
• 桶按时间正序，没有请求的时段也返回，值为 0
• 全部时间都是 UTC
• 每个 from 含、until 不含

举例：在 10 月 1 日 02:30 UTC 请求 24h，起点是 9 月 30 日 02:00 UTC，返回 24 个完整小时桶 + 当前 02:00–02:30 这个不完整桶。

四、totals 和 buckets

• totals：整个范围的总计
• buckets：按时/天拆分
• granularity：自动决定，24h → hour，7d/30d → day
• partial：表示该时段还没结束，不是表示数据没记完

这个区分容易误会：partial: true 的桶里可能已经有完整数据，只是时间窗口还没走完。

五、按模型拆分

curl 'https://ollama.com/api/usage?range=7d&group_by=model' \
  -H "Authorization: Bearer $OLLAMA_API_KEY"

加了 group_by=model 后，totals 和每个 buckets 里都会多出 groups 数组：

{
  "groups": [
    {
      "model": "glm-5.3-flash",
      "request_count": 12,
      "usage_usd": 0.0132,
      "input_tokens": 96000,
      "cached_input_tokens": 60000,
      "output_tokens": 12000
    }
  ]
}

规则：

• 最多 10 个分组，按整个范围的 usage_usd 降序取
• 所有桶用同一套选择和顺序
• 某个桶里没有请求的分组会省略；空桶是 groups: []
• 其余分组合并进 remainder（为空时省略）
• totals 始终包含全部用量，不受 10 个限制影响

旧套餐的差异

如果范围里包含旧套餐的请求，只有请求数可用。此时分组按请求数而非费用排序。

六、限流与安全

项	值
频率限制	10 次/分钟/用户，跨 API Key 和设备共享
建议轮询	每分钟 1 次
超限响应	429 + Retry-After 头（秒）

10 次/分钟是账号级限制，不是 Key 级——多个 Key 分别轮询也会撞上限。

七、团队用量

curl 'https://ollama.com/api/usage?range=7d&scope=team' \
  -H "Authorization: Bearer $OLLAMA_API_KEY"

scope=team 需要团队管理员权限，返回整个团队的用量。普通成员只能看自己的。

八、Python 示例

import os, requests

def usage(range_="7d", group_by_model=False):
    params = {"range": range_}
    if group_by_model:
        params["group_by"] = "model"
    r = requests.get("https://ollama.com/api/usage",
                     params=params,
                     headers={"Authorization": f"Bearer {os.environ['OLLAMA_API_KEY']}"})
    r.raise_for_status()
    return r.json()

d = usage("24h", group_by_model=True)
t = d["totals"]
print(f"请求 {t['request_count']} 次，花费 ${t['usage_usd']:.4f}")
print(f"输入 {t['input_tokens']} tokens（缓存命中 {t['cached_input_tokens']}）")
print(f"输出 {t['output_tokens']} tokens")

for g in t.get("groups", []):
    print(f"  {g['model']:<24} {g['request_count']:>4} 次  ${g['usage_usd']:.4f}")

缓存命中率值得单独算：cached_input_tokens / input_tokens。这个比例高说明提示词前缀复用得好，能显著降低成本。

九、还没上线的能力

官方提到计划增加：自定义时间范围、按 API Key 拆分、团队成员维度拆分（管理员视角）。

常见问题

现象	原因	处理
400	参数非法或重复	只用 range/scope/group_by 各一次
401	Key 无效	检查 Bearer 头
429	超 10 次/分钟	按 Retry-After 等待
数据延迟	用量入库有延迟	等几分钟再查
想看剩余额度	用量的接口给不了	用 /api/balance

动手试

## ① 近 24 小时总花费
curl -s 'https://ollama.com/api/usage?range=24h' \
  -H "Authorization: Bearer $OLLAMA_API_KEY" | python -c "
import sys,json;t=json.load(sys.stdin)['totals'];print(f\"花费 \${t['usage_usd']:.4f}，请求 {t['request_count']} 次\")"

## ② 近 7 天按模型拆分
curl -s 'https://ollama.com/api/usage?range=7d&group_by=model' \
  -H "Authorization: Bearer $OLLAMA_API_KEY" | python -c "
import sys,json
for g in json.load(sys.stdin)['totals'].get('groups',[]):
    print(f\"{g['model']:<26}\${g['usage_usd']:.4f}\")"