Guides · Usage connectors
LiteLLM connector
Bear Lumen reads the spend logs your LiteLLM proxy already keeps: the model, the token counts and the end user of each request. Nothing changes in your code and nothing is deployed.
Before you start
- Your proxy keeps spend logs, which LiteLLM stores in its database, so the proxy runs with one.
- The proxy URL is reachable over HTTPS from the public internet. Bear Lumen reads it from its own servers, so a proxy reachable only inside your network or VPN cannot be connected. URLs that resolve to private network addresses are refused.
- For cost per customer, requests send your customer id as
user, or in aspend_logs_metadatakey. - You have the master key, or another proxy admin key, to create a user and a key.
What Bear Lumen reads
For each request LiteLLM recorded, Bear Lumen keeps only the fields below. They are what it needs to price the request and attribute it to a customer.
| Field | Where it comes from in LiteLLM |
|---|---|
| Request id | The spend log's request id. It lets a re-read recognize a request already imported. |
| Time | When the request started. |
| Model and provider | The model and provider the spend log recorded. |
| Token counts | Prompt and completion tokens, plus cache and reasoning tokens where LiteLLM reports them. |
| Customer id | end_user, which LiteLLM fills from the user parameter of the request. Or a metadata key you map instead. |
| Mapped metadata | The values of the spend_logs_metadata keys you map, and no others. |
| LiteLLM's cost | The spend LiteLLM recorded, kept for comparison only. |
What Bear Lumen never stores
- Prompts, completions, or any other request or response content.
- Metadata or property keys you have not mapped. They are dropped on receipt.
- Requests with no token usage. They are skipped and counted on the connector page.
Requests LiteLLM answered from its cache are skipped, since no provider tokens were spent on them. LiteLLM keeps prompts and responses out of spend logs unless you turn on store_prompts_in_spend_logs. If you have, Bear Lumen drops that content on receipt and stores nothing from it.
Create a read-only key
Give Bear Lumen a key owned by a user with the proxy_admin_viewer role. That role can view all keys and all spend, and cannot create or delete keys or add users. LiteLLM decides what a key may do on its management routes from the role of the user who owns it.
Do not use the master key
The master key can change everything on your proxy. Bear Lumen only needs to read spend logs, and a key with more access than that is a risk with no benefit.
- Create a user with the
proxy_admin_viewerrole. In the LiteLLM Admin UI, open Internal Users, then + New User, and pick that role. Or call/user/newwith your master key, and note theuser_idin the response:bashcurl -X POST 'https://<your-proxy>/user/new' \ -H 'Authorization: Bearer <your-master-key>' \ -H 'Content-Type: application/json' \ -d '{"user_email": "[email protected]", "user_role": "proxy_admin_viewer"}' - Generate a key owned by that user. As a proxy admin, pass the
user_idexplicitly:bashcurl -X POST 'https://<your-proxy>/key/generate' \ -H 'Authorization: Bearer <your-master-key>' \ -H 'Content-Type: application/json' \ -d '{"user_id": "<user_id from the previous step>"}' - Copy the key from the response.
Connect in Bear Lumen
- In the Bear Lumen app, open Settings, Integrations and choose LiteLLM from the usage sources.
- Paste the key. Then enter your proxy's base URL, for example
https://litellm.example.com. - Choose which field is the customer id, and optionally a feature key and dimension keys. See mapping below.
- Choose how much history to import: the last 1, 7 or 30 days.
- Save. Bear Lumen tests the key against LiteLLM first and saves nothing if the test fails. The first import starts once it is saved.
Bear Lumen encrypts the key at rest and shows only its last four characters. From the connector's page you can pause and resume it, rotate the key, run Sync now, or disconnect. Disconnecting deletes the stored key and keeps the usage already imported.
Map customers, features and dimensions
Mapping tells Bear Lumen which of your LiteLLM fields mean what. It is the only way metadata reaches Bear Lumen: a key you do not map is dropped on receipt and never stored.
| Mapping | Default | What you can choose instead |
|---|---|---|
| Customer id | end_user, from the user parameter of each request. | A key that holds your customer id (the keys you can map are described below), or no customer id. With none, usage still counts toward your totals but not toward any customer. |
| Feature | None | One key whose value names the product feature, so cost breaks down by feature. |
| Dimensions | None | Up to 10 more keys, carried over as metadata so you can group cost by them. See Cost attribution. |
Mappable keys are the keys in spend_logs_metadata. You can send it in the request body's metadata, in an x-litellm-spend-logs-metadata header, or set it on a key or team. With the OpenAI Python client pointed at your proxy, a request that sets the customer id and two keys looks like this:
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
user="customer-4821", # recorded as end_user in LiteLLM's spend logs
extra_body={
"metadata": {
"spend_logs_metadata": {"feature": "support-chat", "plan": "pro"},
},
},
)
Use the same customer id as Stripe, or margin stays empty
Per-customer margin needs cost and revenue on the same customer. Bear Lumen links a Stripe customer to a customer id when the Stripe customer's metadata has app_customer_id set to that same value. Set it on your Stripe customers and Bear Lumen links them on its next Stripe sync. If the id in LiteLLM is something else, such as an email address, map a key that holds the id you put in Stripe instead.
When data arrives
Bear Lumen checks the connector every 5 minutes. It only reads requests older than a short settle delay, because LiteLLM can finish recording a request a little after it happened. For LiteLLM that delay is about 5 minutes, so a request usually appears in Bear Lumen about 5 to 10 minutes after it ran. For real-time capture, use the SDK.
When you connect, Bear Lumen imports the history you chose (the last 1, 7 or 30 days), oldest first. A large import is read in steps across several runs, so it can take a while to catch up. It can only import what LiteLLM still holds.
How cost is calculated
Bear Lumen prices every imported request with its own rate cards, the same ones it uses for SDK events, so cost means the same thing whichever way it arrived. LiteLLM's own cost figure is stored next to it for comparison, and the connector's page shows both totals side by side. It is never used as the price.
Models without a rate card wait for one instead of being priced at $0
If a request uses a model Bear Lumen has no rate card for, it is held as pending and priced once a rate card exists. You can add your own rate for a model from Supported models.
Avoid double counting
If the same requests also reach Bear Lumen through the SDK, they are counted twice: once from the SDK and once from LiteLLM. The two copies are not deduplicated. Use one source per workload, for example the connector for traffic that already runs through LiteLLM and the SDK for a service you instrument directly. The connector's page warns when it sees SDK usage alongside it.
For the same reason, Bear Lumen refuses a second live connector for the same LiteLLM proxy. Disconnecting and reconnecting the same LiteLLM proxy does not duplicate anything: requests already imported are recognized and skipped.
Troubleshooting
The connector's page in Settings, Integrations shows its status and the time of its last successful sync. When a connector needs attention, the app shows a banner. After you fix the cause, rotate the key if it changed, then run Sync now from the connector's page to check it.
| Status | What Bear Lumen does | How to fix it with LiteLLM |
|---|---|---|
| Authentication failed | Syncing stops and the connector shows Needs attention. It is not retried automatically. | The key was deleted, has expired, or was mistyped. Generate a new key for the proxy_admin_viewer user and rotate it on the connector page. |
| Permission denied | Syncing stops and the connector shows Needs attention. It is not retried automatically. | The key belongs to a user who cannot read every spend log, for example an internal user. Generate a key owned by a proxy_admin_viewer user. |
| Unsupported version | Syncing stops and the connector shows Needs attention. It is not retried automatically. | Bear Lumen reads LiteLLM's /spend/logs/v2 endpoint. If your proxy does not serve it, upgrade LiteLLM. The same status appears when your proxy reads date ranges in its database timezone and that timezone is not UTC, which LiteLLM versions before v1.83.7 do. Usage would be missed, so syncing stops instead. Upgrade LiteLLM to v1.83.7 or later, or set the timezone of the proxy's database to UTC. |
| Rate limited | Not an error. Syncing waits as long as the tool asks, then continues. | Nothing to do. Syncing catches up on its own. |
| Unreachable | Retried automatically, waiting 1 minute and then twice as long each time, up to 60 minutes. After 6 failures in a row the connector shows Needs attention and keeps retrying every hour. | The proxy did not answer over HTTPS from the internet. Check the URL, its TLS certificate, and that no firewall or VPN blocks it. Addresses on private networks are refused. |
| Insufficient credits | The connector shows Needs attention and retries every hour. Once credits are added it picks up where it stopped. | Your organization's event credit balance ran out. Each imported request is one usage event and spends one credit, the same as an SDK event. See Rate limits for how to add credits. |