view-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

View Usage

查看使用情况

Query daily activity and spend data from a live LiteLLM proxy.

查询运行中的LiteLLM代理的每日活动与支出数据。

Setup

设置

Ask for these if not already known:

LITELLM_BASE_URL  — e.g. https://my-proxy.example.com
LITELLM_API_KEY   — proxy admin key

API reference: https://docs.litellm.ai/docs/proxy/users#get-user-spend

如果尚未知晓，请询问用户以下信息：

LITELLM_BASE_URL  — 示例：https://my-proxy.example.com
LITELLM_API_KEY   — 代理管理员密钥

API参考文档：https://docs.litellm.ai/docs/proxy/users#get-user-spend

Ask the user

询问用户

View by — overall / user / team / org / tag / job (default: overall)
Date range — default to current month if not given
Filter by model? (optional)
Job tag(s)? (optional) — for job cost attribution, ask which request tag identifies the job, for example
```
job:nightly-eval
```
or
```
job=batch-import
```
.

查看维度 — 全局/用户/团队/组织/标签/任务（默认：全局）
日期范围 — 若未指定则默认当前月份
是否按模型过滤？（可选）
任务标签？（可选）— 若要进行任务成本归属，询问用户哪个请求标签用于标识任务，例如
```
job:nightly-eval
```
或
```
job=batch-import
```
。

Job cost attribution

任务成本归属

LiteLLM attributes per-request costs through request tags. For LLM jobs, prefer tagging requests with a stable job label such as

job:<job-name>

and then query tag APIs:

Use
```
/tag/daily/activity?tags=<tag>
```
for daily spend, tokens, request count, and model/provider breakdowns for one or more job tags.
Use
```
/global/spend/tags?tags=<tag>
```
for a top-level spend total by tag over a date range.
If the user asks "which jobs cost the most?", call
```
/global/spend/tags
```
without a
```
tags
```
filter, sort by spend descending, and present the top tags that look like job labels.

LiteLLM通过请求标签来归属每笔请求的成本。对于LLM任务，建议使用稳定的任务标签（如

job:<任务名称>

）标记请求，然后查询标签相关API：

使用
```
/tag/daily/activity?tags=<tag>
```
获取一个或多个任务标签的每日支出、Token数量、请求次数以及模型/服务商细分数据。
使用
```
/global/spend/tags?tags=<tag>
```
获取指定日期范围内按标签统计的总支出。
如果用户询问“哪些任务成本最高？”，调用不带
```
tags
```
过滤条件的
```
/global/spend/tags
```
接口，按支出降序排序，展示看起来像任务标签的前几名。

Endpoints

接口

Overall spend (across all users)

全局支出（所有用户）

bash

curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY"

Overall request and token volume

全局请求与Token总量

bash

curl -s "$BASE/global/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/global/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

By team

按团队统计

bash

curl -s "$BASE/team/daily/activity?team_ids=<team_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/team/daily/activity?team_ids=<team_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

By org

按组织统计

bash

curl -s "$BASE/organization/daily/activity?organization_ids=<org_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/organization/daily/activity?organization_ids=<org_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

By user

按用户统计

bash

curl -s "$BASE/user/daily/activity?user_id=<user_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/user/daily/activity?user_id=<user_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

By tag or job

按标签或任务统计

bash

curl -s "$BASE/tag/daily/activity?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY"

For multiple tags, pass a comma-separated list:

bash

curl -s "$BASE/tag/daily/activity?tags=job:nightly-eval,job:batch-import&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/tag/daily/activity?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY"

多个标签请传入逗号分隔的列表：

bash

curl -s "$BASE/tag/daily/activity?tags=job:nightly-eval,job:batch-import&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY"

Top tag spend

标签支出排行

bash

curl -s "$BASE/global/spend/tags?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

Filter to a specific job tag:

bash

curl -s "$BASE/global/spend/tags?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

bash

curl -s "$BASE/global/spend/tags?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

过滤特定任务标签：

bash

curl -s "$BASE/global/spend/tags?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $KEY"

Response shape

响应格式

json

{
  "results": [
    {
      "date": "2026-03-14",
      "metrics": {
        "spend": 1.23,
        "prompt_tokens": 45000,
        "completion_tokens": 12000,
        "total_tokens": 57000,
        "api_requests": 120,
        "successful_requests": 118,
        "failed_requests": 2
      },
      "breakdown": {
        "models": { "gpt-4o": { "metrics": { "spend": 1.23, ... } } }
      }
    }
  ],
  "metadata": { "page": 1, "page_size": 10, "total_count": 31 }
}

Note: top-level key is

results

(not

data

json

{
  "results": [
    {
      "date": "2026-03-14",
      "metrics": {
        "spend": 1.23,
        "prompt_tokens": 45000,
        "completion_tokens": 12000,
        "total_tokens": 57000,
        "api_requests": 120,
        "successful_requests": 118,
        "failed_requests": 2
      },
      "breakdown": {
        "models": { "gpt-4o": { "metrics": { "spend": 1.23, ... } } }
      }
    }
  ],
  "metadata": { "page": 1, "page_size": 10, "total_count": 31 }
}

注意：顶层键为

results

（而非

data

）。

Summarize with python3

使用Python3汇总

bash

curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY" | python3 -c "
import sys, json
d = json.load(sys.stdin)
rows = d.get('results', [])
print('{:<12} {:>10} {:>12} {:>10}'.format('Date', 'Requests', 'Tokens', 'Spend'))
print('-' * 46)
total_spend = 0
for r in rows:
    m = r.get('metrics', {})
    print('{:<12} {:>10} {:>12} ${:>9.4f}'.format(
        r.get('date', ''),
        m.get('api_requests', 0),
        m.get('total_tokens', 0),
        m.get('spend', 0),
    ))
    total_spend += m.get('spend', 0)
print('-' * 46)
print('{:<12} {:>10} {:>12} ${:>9.4f}'.format('TOTAL', '', '', total_spend))
"

bash

curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
  -H "Authorization: Bearer $KEY" | python3 -c "
import sys, json
d = json.load(sys.stdin)
rows = d.get('results', [])
print('{:<12} {:>10} {:>12} {:>10}'.format('Date', 'Requests', 'Tokens', 'Spend'))
print('-' * 46)
total_spend = 0
for r in rows:
    m = r.get('metrics', {})
    print('{:<12} {:>10} {:>12} ${:>9.4f}'.format(
        r.get('date', ''),
        m.get('api_requests', 0),
        m.get('total_tokens', 0),
        m.get('spend', 0),
    ))
    total_spend += m.get('spend', 0)
print('-' * 46)
print('{:<12} {:>10} {:>12} ${:>9.4f}'.format('TOTAL', '', '', total_spend))
"

Error handling

错误处理

Before processing results, check the HTTP status:

401/403 — invalid or expired
```
LITELLM_API_KEY
```
; ask the user to verify
404 — endpoint not available; check LiteLLM proxy version supports activity endpoints
Empty results — no activity in the given date range; confirm dates are correct

在处理结果前，检查HTTP状态码：

401/403 —
```
LITELLM_API_KEY
```
无效或已过期；请用户验证该密钥
404 — 接口不可用；检查LiteLLM代理版本是否支持活动数据接口
无结果 — 指定日期范围内无活动数据；确认日期是否正确

Instructions

操作步骤

Ask for date range — default to current month.
Run the appropriate endpoint. For job attribution, prefer tag endpoints and ask for the job tag if it was not provided.
Print a table: Date | Requests | Tokens | Spend.
Show totals row at the bottom.
Highlight any days with
```
failed_requests > 0
```
.
If
```
metadata.total_pages > 1
```
, offer to fetch remaining pages.

询问日期范围 — 默认当前月份。
调用对应的接口。若进行任务成本归属，优先使用标签接口，若用户未提供任务标签则询问。
打印表格：日期 | 请求次数 | Token数量 | 支出。
在底部显示总计行。
高亮显示任何
```
failed_requests > 0
```
的日期。
如果
```
metadata.total_pages > 1
```
，询问用户是否需要获取剩余页面的数据。