Guides · Usage connectors

Usage connectors

If your LLM calls already go through Helicone, Langfuse or LiteLLM, a usage connector reads the usage that tool records and brings it into Bear Lumen on a schedule. There is no code to change and nothing to deploy. Cost, margin, attribution and alerts then work the same as they do for SDK data.

Connectors or the SDK

Both land in the same cost data, so every report treats them the same. The difference is how the data gets there, and what only the SDK can send.

AspectUsage connectorSDK
Code changeNone. You connect it in the app.Install the SDK and track each call.
What it capturesModel, token counts, customer id, and the keys you map, for each request.The same, plus outcomes, spans and sessions for agentic work.
FreshnessEvery 5 minutes, after a short settle delay.Real time: each call is sent as it happens.
HistoryImports the last 1, 7 or 30 days when you connect.Starts when you add it.

Start with a connector to see cost without a deploy. Add the SDK where you need outcomes, spans or real-time capture: see the SDK quickstart and Tracing agentic work.

Use one source per workload

Requests sent to Bear Lumen by the SDK and also read by a connector are counted twice. They are not deduplicated. Pick one source for each workload.

Supported tools

ToolKey Bear Lumen needsWhere it pointsCustomer id by defaultSettle delay
HeliconeSecret API key with read and write permissionUS or EU regionHelicone-User-IdAbout 5 minutes
LangfuseProject API key with Viewer permissionEU, US, JP or HIPAA cloud region, or a self-hosted URL (v4 or later)userIdAbout 10 minutes
LiteLLMKey owned by a proxy_admin_viewer userYour proxy URL, over HTTPS, reachable from the public internetuserAbout 5 minutes

How connecting works

  1. Create a read-only key in your tool. Each tool page shows the least access Bear Lumen needs.
  2. Connect it in Bear Lumen. Open Settings, Integrations, pick the tool, paste the key, and choose the region or URL. Bear Lumen tests the key before it saves anything.
  3. Map your fields. Choose which field is the customer id, and optionally a feature key and dimension keys.
  4. Choose your history. Import the last 1, 7 or 30 days. After that, new usage arrives every 5 minutes.

What a connector stores

For each request: the model, the token counts by type, the customer id, the values of the keys you mapped, and the tool's own cost figure for comparison. Bear Lumen prices the request itself, with its own rate cards. It never stores prompts, responses, or metadata you did not map, and it encrypts your key at rest.

Margin needs the same customer id as Stripe

Bear Lumen matches cost to revenue by customer. Set app_customer_id in each Stripe customer's metadata to the id your connector reads as the customer id, and Bear Lumen links them on its next Stripe sync.

Limits

  • Connectors import usage only. Outcomes, spans and sessions need the SDK.
  • If a tool changes a request's token counts after Bear Lumen imported it, the imported cost is not updated.
  • Disconnecting deletes the stored key and keeps the usage already imported. Reconnecting the same source does not import anything twice.

Next steps