SuperPenguin Docs
Provider Integrations

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 byTag
Agentagent:<name>
Customercustomer:<id>
Featurefeature:<name>
Teamteam:<name>
Environmentenv:<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.