# View Usage

> >

- **Type:** Skill
- **Install:** `agentstack add skill-berriai-litellm-skills-view-usage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BerriAI](https://agentstack.voostack.com/s/berriai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BerriAI](https://github.com/BerriAI)
- **Source:** https://github.com/BerriAI/litellm-skills/tree/main/view-usage
- **Website:** https://github.com/BerriAI/litellm-skills

## Install

```sh
agentstack add skill-berriai-litellm-skills-view-usage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

1. **View by** — overall / user / team / org / tag / job (default: overall)
2. **Date range** — default to current month if not given
3. **Filter by model?** (optional)
4. **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:` and then query
tag APIs:

- Use `/tag/daily/activity?tags=` for daily spend, tokens, request count,
  and model/provider breakdowns for one or more job tags.
- Use `/global/spend/tags?tags=` 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=&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=&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=&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=&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=&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('{:10} {:>12} {:>10}'.format('Date', 'Requests', 'Tokens', 'Spend'))
print('-' * 46)
total_spend = 0
for r in rows:
    m = r.get('metrics', {})
    print('{: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('{: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

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BerriAI](https://github.com/BerriAI)
- **Source:** [BerriAI/litellm-skills](https://github.com/BerriAI/litellm-skills)
- **License:** MIT
- **Homepage:** https://github.com/BerriAI/litellm-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-berriai-litellm-skills-view-usage
- Seller: https://agentstack.voostack.com/s/berriai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.