Add litellm-access skill for querying LiteLLM proxy models and usage stats

2026-07-13 15:26:24 +04:00
commit cb720a0c34
1 changed files with 170 additions and 0 deletions
@@ -0,0 +1,170 @@
+---
+name: litellm-access
+description: Use when the user wants to query a LiteLLM proxy instance for available models, providers, usage statistics, spend reports, or token/cost data. Trigger on keywords like "litellm", "llm models", "model list", "usage stats", "spend report", "token usage", "cost tracking". Requires LITELLM_URL and LITELLM_API_KEY environment variables.
+---
+
+# LiteLLM Access Skill
+
+Query a LiteLLM proxy instance to read models, providers, usage statistics, and spend data.
+
+## Configuration
+
+This skill requires two environment variables:
+
+- `LITELLM_URL` — The base URL of the LiteLLM proxy (e.g., `http://localhost:4000` or `https://your-proxy.example.com`)
+- `LITELLM_API_KEY` — A valid LiteLLM API key (virtual key or master key)
+
+All API calls use the header: `Authorization: Bearer $LITELLM_API_KEY`
+
+Use `curl` for all requests. Replace `$LITELLM_URL` and `$LITELLM_API_KEY` with the actual values from the environment.
+
+## Available Operations
+
+### 1. List All Configured Models
+
+Returns all models configured on the proxy with their provider, model info, and deployment details.
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" "$LITELLM_URL/v1/model/info" | jq .
+```
+
+Key fields in response:
+- `model_name` — User-facing model name
+- `litellm_params.model` — Actual model identifier sent to provider
+- `litellm_params.api_base` — Provider API endpoint
+- `model_info` — Additional metadata (access groups, supported environments)
+
+### 2. OpenAI-Compatible Model List
+
+Returns models in OpenAI-compatible format:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" "$LITELLM_URL/v1/models" | jq .
+```
+
+### 3. Spend by API Key
+
+List all API keys ordered by spend:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" "$LITELLM_URL/spend/keys" | jq .
+```
+
+### 4. Spend by User
+
+List all users ordered by spend:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" "$LITELLM_URL/spend/users" | jq .
+```
+
+### 5. Global Spend Report
+
+Generate spend reports grouped by team, customer, key, or internal user.
+
+**Group by team:**
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/global/spend/report?start_date=2024-01-01&end_date=2024-12-31&group_by=team" | jq .
+```
+
+**Group by customer:**
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/global/spend/report?start_date=2024-01-01&end_date=2024-12-31&group_by=customer" | jq .
+```
+
+**For a specific API key:**
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/global/spend/report?start_date=2024-01-01&end_date=2024-12-31&api_key=sk-your-key" | jq .
+```
+
+**For a specific internal user:**
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/global/spend/report?start_date=2024-01-01&end_date=2024-12-31&internal_user_id=user-id" | jq .
+```
+
+Parameters:
+- `start_date` — Start date (YYYY-MM-DD)
+- `end_date` — End date (YYYY-MM-DD)
+- `group_by` — One of: `team`, `customer`, `api_key`, `internal_user_id`
+- `api_key` — (optional) Filter by specific API key
+- `internal_user_id` — (optional) Filter by specific internal user
+
+### 6. Daily Spend Breakdown
+
+Get granular daily usage data broken down by model, provider, and API key:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/user/daily/activity?start_date=2024-01-01&end_date=2024-01-31" | jq .
+```
+
+Response includes per-day metrics (spend, tokens, API requests) with breakdowns by model, provider, and API key.
+
+### 7. Transaction Logs
+
+Get individual transaction logs:
+
+```bash
+# Summarized (default)
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/spend/logs?start_date=2024-01-01&end_date=2024-01-02" | jq .
+
+# Individual transactions
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/spend/logs?start_date=2024-01-01&end_date=2024-01-02&summarize=false" | jq .
+```
+
+### 8. User Info
+
+Get details and spend for a specific user:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/user/info?user_id=USER_ID" | jq .
+```
+
+### 9. Team Info
+
+Get details and spend for a specific team:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/team/info?team_id=TEAM_ID" | jq .
+```
+
+### 10. Key Info
+
+Get details and spend for a specific API key:
+
+```bash
+curl -s -H "Authorization: Bearer $LITELLM_API_KEY" \
+  "$LITELLM_URL/key/info?key=sk-your-key" | jq .
+```
+
+## Response Handling
+
+- All endpoints return JSON
+- Spend values are in USD
+- Token counts include `prompt_tokens`, `completion_tokens`, and `total_tokens`
+- Dates use ISO 8601 format
+- Hashed API keys are truncated in responses for security
+
+## Error Handling
+
+Common errors:
+- `401 Unauthorized` — Invalid or missing API key
+- `404 Not Found` — Endpoint not available (proxy may not have database configured)
+- `500 Internal Server Error` — Proxy server issue
+
+If spend endpoints return empty arrays, the proxy may not have a database configured for spend tracking. Inform the user that spend tracking requires a PostgreSQL database.
+
+## Tips
+
+- Always use `jq .` to format JSON output for readability
+- When date ranges are large, responses may be verbose — consider narrowing the range
+- The `/v1/model/info` endpoint is the most reliable for getting complete model configuration
+- For quick overviews, start with `/v1/model/info` and `/spend/keys`