Guides · Usage connectors

Langfuse connector

Bear Lumen reads the generations and embeddings Langfuse already records for a project: the model, the token usage and the user id. Nothing changes in your code and nothing is deployed.

Before you start

  • Langfuse Cloud, or self-hosted Langfuse v4 or later. Bear Lumen reads Langfuse's v2 observations API, which self-hosted Langfuse serves from v4. On v3, upgrade first.
  • For cost per customer, your traces set userId, or a metadata key holds your customer id.
  • You are an Owner or Admin of the Langfuse project, so you can create API keys.

What Bear Lumen reads

For each request Langfuse 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 Langfuse
Generation idThe observation id of each generation. It lets a re-read recognize a generation already imported.
TimeThe generation's start time.
ModelThe model Langfuse recorded on the generation.
Token countsInput and output tokens, plus cache read, cache write and reasoning tokens where the generation's usage details report them.
Customer idThe generation's userId. Or a metadata key you map instead.
Mapped metadataThe values of the top-level metadata keys you map, and no others.
Langfuse's costThe cost Langfuse calculated, 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.

Bear Lumen reads observations of type generation and embedding, the two types that carry token usage, and asks Langfuse only for the field groups it needs. Input and output are not among them, so prompts and completions are never sent to Bear Lumen. When you map metadata keys, Langfuse returns the generation's metadata and Bear Lumen keeps only the keys you mapped.

Create a Viewer key

Since 16 October 2026, Langfuse lets you choose a permission level when you create a project API key. Viewer is read-only access to the project's data, which is everything Bear Lumen needs.

  1. In Langfuse, open the project, then Project Settings, then API Keys.
  2. Click Create new API keys. Under Permissions, choose Viewer. A key's permission cannot be changed later, so pick it now. If your Langfuse does not offer the choice yet, a Full access key also works.
  3. Optionally set an expiry date. If you do, rotate the key in Bear Lumen before it expires.
  4. Copy the public key and the secret key. Langfuse shows the secret key only once.

Connect in Bear Lumen

  1. In the Bear Lumen app, open Settings, Integrations and choose Langfuse from the usage sources.
  2. Paste the key. Langfuse keys come in two parts, so paste both the public key and the secret key. Then choose where the project lives: a Langfuse Cloud region from the table below, or your self-hosted URL, which must be reachable from the public internet. Bear Lumen reads the project the key belongs to.
  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 Langfuse 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.

Langfuse Cloud regionHost
EUcloud.langfuse.com
USus.cloud.langfuse.com
JPjp.cloud.langfuse.com
HIPAAhipaa.cloud.langfuse.com

Map customers, features and dimensions

Mapping tells Bear Lumen which of your Langfuse 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 iduserId, set on traces and inherited by the generations inside them.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 top-level keys of a generation's metadata that hold a single value. Nested objects and lists are not read. In the Langfuse Python SDK, propagate_attributes sets both the user id and metadata for every generation inside it (the JS/TS SDK has propagateAttributes):

Python
from langfuse import observe, propagate_attributes

@observe()
def answer(question, customer_id):
    # Every generation created inside this block carries the user id.
    with propagate_attributes(user_id=customer_id, metadata={"feature": "support-chat"}):
        return call_llm(question)

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 Langfuse 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 Langfuse can finish recording a request a little after it happened. For Langfuse that delay is about 10 minutes, so a request usually appears in Bear Lumen about 10 to 15 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 Langfuse 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. Langfuse'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 Langfuse. The two copies are not deduplicated. Use one source per workload, for example the connector for traffic that already runs through Langfuse 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 Langfuse project. Disconnecting and reconnecting the same Langfuse project 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 Langfuse
Authentication failedSyncing stops and the connector shows Needs attention. It is not retried automatically.The public and secret key do not match, the key was deleted or has expired, or it belongs to another region or instance. Create a new key and rotate it on the connector page.
Permission deniedSyncing stops and the connector shows Needs attention. It is not retried automatically.The key has Ingestion or Scores ingestion permission, which cannot read. Create a Viewer key.
Unsupported versionSyncing stops and the connector shows Needs attention. It is not retried automatically.Your self-hosted Langfuse is older than v4 and does not serve the v2 observations API. Upgrade to v4 or later.
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.Langfuse did not answer, or the region or self-hosted URL is wrong. Check the URL. A self-hosted instance must be reachable from the public internet.
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