LiteLLM proxy
Connect a LiteLLM proxy with a read-only key and see spend by agent, customer and feature, with no SDK.
SuperPenguin reads your LiteLLM proxy's spend logs. Every request routed through the proxy is counted, whatever the upstream provider and whatever language your services are written in. To split spend by agent, customer or feature, add a tag to each request at the proxy. You don't need to install anything in your services.
1. Create a read-only key
Use a key for a LiteLLM user with the proxy_admin_viewer role. It can read spend logs, but it can't call models or change settings.
In the LiteLLM Admin UI, open Internal Users, add a user with the Admin Viewer role, then create a key for that user. Or with the API:
curl -X POST "https://your-proxy.example.com/user/new" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{"user_email": "[email protected]", "user_role": "proxy_admin_viewer"}'The response includes the new user's key.
Other keys that work:
- A team admin's key. SuperPenguin imports that team's spend only.
- The master key. This still works, but a read-only key is safer.
An ordinary user key only sees that user's own requests. SuperPenguin rejects it when you connect, so you don't end up with partial numbers.
2. Connect
Open Integrations, choose LiteLLM, and enter your proxy URL and the key. SuperPenguin checks what the key can read before saving it.
3. Tag requests
Add one tag per dimension you want to group by:
| Group by | Tag |
|---|---|
| Agent | agent:<name> |
| Customer | customer:<id> |
| Feature | feature:<name> |
| Team | team:<name> |
| Environment | env:<name> |
Send tags in the x-litellm-tags header (comma-separated) or the request body.
Both work on every LiteLLM version that SuperPenguin supports.
curl https://your-proxy.example.com/v1/chat/completions \
-H "Authorization: Bearer $SERVICE_KEY" \
-H "Content-Type: application/json" \
-H "x-litellm-tags: agent:support-triage,customer:acme,feature:ticket-summary" \
-d '{"model": "claude-sonnet", "messages": [{"role": "user", "content": "Hi"}]}'In the body, use "tags": ["agent:support-triage", "customer:acme"] or
"metadata": {"tags": [...]}. If you send both the header and body tags,
LiteLLM keeps the body tags.
Go
req, _ := http.NewRequest("POST", proxyURL+"/v1/chat/completions", body)
req.Header.Set("Authorization", "Bearer "+serviceKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-litellm-tags", "agent:support-triage,customer:"+customerID)Ruby
req = Net::HTTP::Post.new(URI("#{proxy_url}/v1/chat/completions"))
req["Authorization"] = "Bearer #{service_key}"
req["Content-Type"] = "application/json"
req["x-litellm-tags"] = "agent:support-triage,customer:#{customer_id}"C (libcurl)
struct curl_slist *h = NULL;
h = curl_slist_append(h, "Content-Type: application/json");
h = curl_slist_append(h, "x-litellm-tags: agent:support-triage,customer:acme");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, h);Plain metadata keys
You can also send named fields instead of tags, in body
metadata.spend_logs_metadata or the x-litellm-spend-logs-metadata JSON
header (LiteLLM 1.81 and later):
{"metadata": {"spend_logs_metadata": {"agent": "invoice-bot", "customer_id": "globex", "feature": "invoice-extract"}}}Recognized keys are agent, customer or customer_id, feature, team,
and env or environment. Other keys show up as custom tags you can group
by. If a request has both a tag and a metadata key for the same dimension, the
tag wins.
Dedicated and pooled agents
- Dedicated: give each agent its own LiteLLM key. Untagged requests are
grouped under the key's alias. To set the name once, add
"spend_logs_metadata": {"agent": "<name>"}to the key's metadata. Every request on that key then carries it. - Pooled: agents that share a key send
agent:<name>on each request.
If a request has no customer tag, SuperPenguin uses the request's user
field. If it has no team tag, it uses the LiteLLM team's name.
See it
Open Attribution and group by agent, customer, feature, team or environment. Requests from the last few hours show up right away. The previous week fills in within a day; earlier history keeps its totals without the per-agent split.
Supported versions
Per-request detail and tags need LiteLLM 1.81 or later, the first version with
/spend/logs/v2. Older proxies import daily totals only.