View Usage

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

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

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 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.

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"

Overall request and token volume

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"

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"

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"

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"

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"

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

Summarize with 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))
"

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

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.

view-usage

NPX Install

Tags

SKILL.md Content

View Usage

Setup

Ask the user

Job cost attribution

Endpoints

Overall spend (across all users)

Overall request and token volume

By team

By org

By user

By tag or job

Top tag spend

Response shape

Summarize with python3

Error handling

Instructions