Script location
The script is located in the same directory as this SKILL.md:
sub2api-usage/scripts/fetch_usage.py
How to run
Use uv run to execute (the script declares dependencies inline via PEP 723, no additional installation required):
# 普通查询（只看当前）
uv run sub2api-usage/scripts/fetch_usage.py
# 周期报告（与上次快照对比，并保存本次为新快照）
uv run sub2api-usage/scripts/fetch_usage.py --report
The script outputs pure JSON; read the data from it and answer the user in natural language.
Environment variables
The script loads configuration by priority: first read ~/.openclaw/.env(global), then read sub2api-usage/.env(skill directory, higher priority can override global values). The following variables are required:
| Variable | Description |
|---|---|
SUB2API_URL |
Sub2API service address |
SUB2API_ADMIN_KEY |
Admin API Key |
SUB2API_USER_ID |
User ID to query |
Output field description
summary
| Field | Meaning |
|---|---|
total_today_tokens |
Total tokens for all keys today (including cache) |
total_today_cost |
Total spend today ($) |
total_all_cost |
Cumulative total spend for all keys ($) |
keys[](each key)
| Field | Meaning |
|---|---|
today_tokens |
Token usage today (including cache) |
today_input/output/cache |
Token breakdown |
today_requests |
Number of requests today |
today_cost |
Spend today ($) |
total_cost |
Cumulative total spend ($) |
usage_1d / limit_1d / pct_1d |
Daily limit used / daily limit ($) / percentage% |
usage_7d / limit_7d / pct_7d |
Weekly limit used / weekly limit ($) / percentage% |
delta(only --report mode)
delta is only validbetween two runs on the same day. When crossing days, the today counter has been reset, and the script will set delta to null and attach delta_note to explain the reason.
| Field | Meaning |
|---|---|
period_from/to |
Timestamps of the two snapshots |
delta_tokens |
New tokens added during the period |
delta_cost |
New spend added during the period ($) |
key_deltas[] |
Delta for each key, sorted in descending order by usage |
Answering guidelines
General usage query
- Summary first: first state today's total Mtoken (
total_today_tokens / 1_000_000, keep two decimal places) and spend. - Limit warnings：
pct_1d >= 80%orpct_7d >= 80%, clearly mark a warning and state the remaining quota. - Expand as needed: if the user asks "who used how much", list each key's today Mtoken and spend; if they only ask for the total, just give the total.
- Number format: convert tokens to Mtoken (keep two decimal places), keep spend to two decimal places but accurate to cents (
$1.53）。
Periodic report (--report）
when delta is valid (two runs on the same day)
Focus on showingchanges, rather than static status:
- Period summary: this segment added X Mtoken, $Y, time interval HH:MM -> HH:MM.
- Activity ranking: list the top 3 keys by usage in this segment (highest delta_tokens), and point out who "used heavily".
- Today's cumulative: Today's total so far is X Mtoken, $Y; each key's percentage of the daily limit.
- Limit alerts: Keys approaching or exceeding the limit are listed separately, noting how much remains.
- Quiet period: If a key's usage delta is 0, there is no need to list them one by one; a single sentence "the remaining N keys had no activity in this period" suffices.
When delta is invalid (snapshot spans days or no historical snapshot)
When delta is null , it indicates the snapshot is from a different date (or does not exist). In this case:
- Briefly explain the reason (e.g., "the last snapshot was X days ago; after the date change, the today counter has been reset").
- Report directly based on today's cumulative data, in the same format as "regular usage query".
- Do not attempt to interpret the delta value, and do not output meaningless negative numbers.
Note：
usage_1d/usage_7dis the system's rolling-window usage measured in **cost ($)**, which differs slightly in source fromtoday_cost(the time window calculation method is different). Limit alerts are based onpct_1d/pct_7d.