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 a spend_logs_metadata key.
  • 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.

FieldWhere it comes from in LiteLLM
Request idThe spend log's request id. It lets a re-read recognize a request already imported.
TimeWhen the request started.
Model and providerThe model and provider the spend log recorded.
Token countsPrompt and completion tokens, plus cache and reasoning tokens where LiteLLM reports them.
Customer idend_user, which LiteLLM fills from the user parameter of the request. Or a metadata key you map instead.
Mapped metadataThe values of the spend_logs_metadata keys you map, and no others.
LiteLLM's costThe 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.

  1. Create a user with the proxy_admin_viewer role. In the LiteLLM Admin UI, open Internal Users, then + New User, and pick that role. Or call /user/new with your master key, and note the user_id in the response:
    bash
    curl -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"}'
    
  2. Generate a key owned by that user. As a proxy admin, pass the user_id explicitly:
    bash
    curl -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>"}'
    
  3. Copy the key from the response.

Connect in Bear Lumen

  1. In the Bear Lumen app, open Settings, Integrations and choose LiteLLM from the usage sources.
  2. Paste the key. Then enter your proxy's base URL, for example https://litellm.example.com.
  3. Choose which field is the customer id, and optionally a feature key and dimension keys. See mapping below.
  4. Choose how much history to import: the last 1, 7 or 30 days.
  5. 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.

MappingDefaultWhat you can choose instead
Customer idend_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.
FeatureNoneOne key whose value names the product feature, so cost breaks down by feature.
DimensionsNoneUp 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:

Python
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.

StatusWhat Bear Lumen doesHow to fix it with LiteLLM
Authentication failedSyncing 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 deniedSyncing 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 versionSyncing 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 limitedNot an error. Syncing waits as long as the tool asks, then continues.Nothing to do. Syncing catches up on its own.
UnreachableRetried 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 creditsThe 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.

Next steps