view-usage

Name: view-usage
Author: BerriAI

70stars10forks

How to install view-usage?

berriai/litellm-skills/view-usage

$npx -y skills add BerriAI/litellm-skills --skill view-usage

Installs into the current project.

Summary

Query spend and token activity on a live LiteLLM proxy. Shows daily usage broken down by user, team, org, tag, job, or model. Use when the user wants to see costs, token counts, request volume, or job-level attribution for a given date range.

Files · 1

View on GitHub

SKILL.md

1	# View Usage
2
3	Query daily activity and spend data from a live LiteLLM proxy.
4
5	## Setup
6
7	Ask for these if not already known:
8	```
9	LITELLM_BASE_URL — e.g. https://my-proxy.example.com
10	LITELLM_API_KEY — proxy admin key
11	```
12
13	API reference: https://docs.litellm.ai/docs/proxy/users#get-user-spend
14
15	## Ask the user
16
17	1. View by — overall / user / team / org / tag / job (default: overall)
18	2. Date range — default to current month if not given
19	3. Filter by model? (optional)
20	4. Job tag(s)? (optional) — for job cost attribution, ask which request
21	tag identifies the job, for example `job:nightly-eval` or `job=batch-import`.
22
23	## Job cost attribution
24
25	LiteLLM attributes per-request costs through request tags. For LLM jobs, prefer
26	tagging requests with a stable job label such as `job:<job-name>` and then query
27	tag APIs:
28
29	- Use `/tag/daily/activity?tags=<tag>` for daily spend, tokens, request count,
30	and model/provider breakdowns for one or more job tags.
31	- Use `/global/spend/tags?tags=<tag>` for a top-level spend total by tag over a
32	date range.
33	- If the user asks "which jobs cost the most?", call `/global/spend/tags`
34	without a `tags` filter, sort by spend descending, and present the top tags
35	that look like job labels.
36
37	## Endpoints
38
39	### Overall spend (across all users)
40	```bash
41	curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
42	-H "Authorization: Bearer $KEY"
43	```
44
45	### Overall request and token volume
46	```bash
47	curl -s "$BASE/global/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
48	-H "Authorization: Bearer $KEY"
49	```
50
51	### By team
52	```bash
53	curl -s "$BASE/team/daily/activity?team_ids=<team_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
54	-H "Authorization: Bearer $KEY"
55	```
56
57	### By org
58	```bash
59	curl -s "$BASE/organization/daily/activity?organization_ids=<org_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
60	-H "Authorization: Bearer $KEY"
61	```
62
63	### By user
64	```bash
65	curl -s "$BASE/user/daily/activity?user_id=<user_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
66	-H "Authorization: Bearer $KEY"
67	```
68
69	### By tag or job
70	```bash
71	curl -s "$BASE/tag/daily/activity?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
72	-H "Authorization: Bearer $KEY"
73	```
74
75	For multiple tags, pass a comma-separated list:
76	```bash
77	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" \
78	-H "Authorization: Bearer $KEY"
79	```
80
81	### Top tag spend
82	```bash
83	curl -s "$BASE/global/spend/tags?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
84	-H "Authorization: Bearer $KEY"
85	```
86
87	Filter to a specific job tag:
88	```bash
89	curl -s "$BASE/global/spend/tags?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
90	-H "Authorization: Bearer $KEY"
91	```
92
93	## Response shape
94
95	```json
96	{
97	"results": [
98	{
99	"date": "2026-03-14",
100	"metrics": {
101	"spend": 1.23,
102	"prompt_tokens": 45000,
103	"completion_tokens": 12000,
104	"total_tokens": 57000,
105	"api_requests": 120,
106	"successful_requests": 118,
107	"failed_requests": 2
108	},
109	"breakdown": {
110	"models": { "gpt-4o": { "metrics": { "spend": 1.23, ... } } }
111	}
112	}
113	],
114	"metadata": { "page": 1, "page_size": 10, "total_count": 31 }
115	}
116	```
117
118	Note: top-level key is `results` (not `data`).
119
120	## Summarize with python3
121
122	```bash
123	curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
124	-H "Authorization: Bearer $KEY" \| python3 -c "
125	import sys, json
126	d = json.load(sys.stdin)
127	rows = d.get('results', [])
128	print('{:<12} {:>10} {:>12} {:>10}'.format('Date', 'Requests', 'Tokens', 'Spend'))
129	print('-' * 46)
130	total_spend = 0
131	for r in rows:
132	m = r.get('metrics', {})
133	print('{:<12} {:>10} {:>12} ${:>9.4f}'.format(
134	r.get('date', ''),
135	m.get('api_requests', 0),
136	m.get('total_tokens', 0),
137	m.get('spend', 0),
138	))
139	total_spend += m.get('spend', 0)
140	print('-' * 46)
141	print('{:<12} {:>10} {:>12} ${:>9.4f}'.format('TOTAL', '', '', total_spend))
142	"
143	```
144
145	## Error handling
146
147	Before processing results, check the HTTP status:
148	- 401/403 — invalid or expired `LITELLM_API_KEY`; ask the user to verify
149	- 404 — endpoint not available; check LiteLLM proxy version supports activity endpoints
150	- Empty results — no activity in the given date range; confirm dates are correct
151
152	## Instructions
153
154	1. Ask for date range — default to current month.
155	2. Run the appropriate endpoint. For job attribution, prefer tag endpoints and
156	ask for the job tag if it w

People who liked this also viewed

6 picks

Type

view-usage

70stars10forks

View on GitHub

How to install view-usage?

berriai/litellm-skills/view-usage

$npx -y skills add BerriAI/litellm-skills --skill view-usage

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# View Usage
2
3	Query daily activity and spend data from a live LiteLLM proxy.
4
5	## Setup
6
7	Ask for these if not already known:
8	```
9	LITELLM_BASE_URL — e.g. https://my-proxy.example.com
10	LITELLM_API_KEY — proxy admin key
11	```
12
13	API reference: https://docs.litellm.ai/docs/proxy/users#get-user-spend
14
15	## Ask the user
16
17	1. View by — overall / user / team / org / tag / job (default: overall)
18	2. Date range — default to current month if not given
19	3. Filter by model? (optional)
20	4. Job tag(s)? (optional) — for job cost attribution, ask which request
21	tag identifies the job, for example `job:nightly-eval` or `job=batch-import`.
22
23	## Job cost attribution
24
25	LiteLLM attributes per-request costs through request tags. For LLM jobs, prefer
26	tagging requests with a stable job label such as `job:<job-name>` and then query
27	tag APIs:
28
29	- Use `/tag/daily/activity?tags=<tag>` for daily spend, tokens, request count,
30	and model/provider breakdowns for one or more job tags.
31	- Use `/global/spend/tags?tags=<tag>` for a top-level spend total by tag over a
32	date range.
33	- If the user asks "which jobs cost the most?", call `/global/spend/tags`
34	without a `tags` filter, sort by spend descending, and present the top tags
35	that look like job labels.
36
37	## Endpoints
38
39	### Overall spend (across all users)
40	```bash
41	curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
42	-H "Authorization: Bearer $KEY"
43	```
44
45	### Overall request and token volume
46	```bash
47	curl -s "$BASE/global/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
48	-H "Authorization: Bearer $KEY"
49	```
50
51	### By team
52	```bash
53	curl -s "$BASE/team/daily/activity?team_ids=<team_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
54	-H "Authorization: Bearer $KEY"
55	```
56
57	### By org
58	```bash
59	curl -s "$BASE/organization/daily/activity?organization_ids=<org_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
60	-H "Authorization: Bearer $KEY"
61	```
62
63	### By user
64	```bash
65	curl -s "$BASE/user/daily/activity?user_id=<user_id>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
66	-H "Authorization: Bearer $KEY"
67	```
68
69	### By tag or job
70	```bash
71	curl -s "$BASE/tag/daily/activity?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
72	-H "Authorization: Bearer $KEY"
73	```
74
75	For multiple tags, pass a comma-separated list:
76	```bash
77	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" \
78	-H "Authorization: Bearer $KEY"
79	```
80
81	### Top tag spend
82	```bash
83	curl -s "$BASE/global/spend/tags?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
84	-H "Authorization: Bearer $KEY"
85	```
86
87	Filter to a specific job tag:
88	```bash
89	curl -s "$BASE/global/spend/tags?tags=<tag>&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
90	-H "Authorization: Bearer $KEY"
91	```
92
93	## Response shape
94
95	```json
96	{
97	"results": [
98	{
99	"date": "2026-03-14",
100	"metrics": {
101	"spend": 1.23,
102	"prompt_tokens": 45000,
103	"completion_tokens": 12000,
104	"total_tokens": 57000,
105	"api_requests": 120,
106	"successful_requests": 118,
107	"failed_requests": 2
108	},
109	"breakdown": {
110	"models": { "gpt-4o": { "metrics": { "spend": 1.23, ... } } }
111	}
112	}
113	],
114	"metadata": { "page": 1, "page_size": 10, "total_count": 31 }
115	}
116	```
117
118	Note: top-level key is `results` (not `data`).
119
120	## Summarize with python3
121
122	```bash
123	curl -s "$BASE/user/daily/activity?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&page_size=30" \
124	-H "Authorization: Bearer $KEY" \| python3 -c "
125	import sys, json
126	d = json.load(sys.stdin)
127	rows = d.get('results', [])
128	print('{:<12} {:>10} {:>12} {:>10}'.format('Date', 'Requests', 'Tokens', 'Spend'))
129	print('-' * 46)
130	total_spend = 0
131	for r in rows:
132	m = r.get('metrics', {})
133	print('{:<12} {:>10} {:>12} ${:>9.4f}'.format(
134	r.get('date', ''),
135	m.get('api_requests', 0),
136	m.get('total_tokens', 0),
137	m.get('spend', 0),
138	))
139	total_spend += m.get('spend', 0)
140	print('-' * 46)
141	print('{:<12} {:>10} {:>12} ${:>9.4f}'.format('TOTAL', '', '', total_spend))
142	"
143	```
144
145	## Error handling
146
147	Before processing results, check the HTTP status:
148	- 401/403 — invalid or expired `LITELLM_API_KEY`; ask the user to verify
149	- 404 — endpoint not available; check LiteLLM proxy version supports activity endpoints
150	- Empty results — no activity in the given date range; confirm dates are correct
151
152	## Instructions
153
154	1. Ask for date range — default to current month.
155	2. Run the appropriate endpoint. For job attribution, prefer tag endpoints and
156	ask for the job tag if it w

People who liked this also viewed

6 picks

Type