Guides · Usage connectors
Helicone connector
Bear Lumen reads the usage Helicone already records for every request that goes through it: the model, the token counts and the user id. Nothing changes in your code and nothing is deployed.
Before you start
- Your LLM requests already go through Helicone, in its US or EU region.
- For cost per customer, each request carries your customer id in the
Helicone-User-Idheader or in a custom property. - You can create API keys in your Helicone organization.
Helicone is in maintenance mode
Helicone announced in March 2026 that, after joining Mintlify, it runs in maintenance mode: security updates, new models and fixes continue. The connector works for as long as Helicone's API does. Read Helicone's announcement.
What Bear Lumen reads
For each request Helicone 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 Helicone |
|---|---|
| Request id | Helicone's id for the request. It lets a re-read recognize a request already imported. |
| Time | When the request started. |
| Model and provider | The model and provider Helicone recorded. |
| Token counts | Input and output tokens, plus cache read, cache write and reasoning tokens where Helicone reports them. |
| Customer id | The request's user id (request_user_id), which Helicone takes from the Helicone-User-Id header. Or a property you map instead. |
| Mapped properties | The values of the custom properties you map, and no others. |
| Helicone's cost | Helicone's own cost figure, 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.
How request bodies are handled
Helicone's standard request API returns each request's body and response along with its usage record. Bear Lumen discards them as each page arrives. Nothing from them is stored or logged.
If your workspace has Helicone's SQL API (HQL), Bear Lumen queries it instead and selects only usage columns, so the bodies are never sent to Bear Lumen at all. Helicone offers HQL to selected workspaces; you can request access from the HQL page in Helicone.
To keep content out of Helicone itself, send these headers on your requests. Helicone documents that it then does not store the request or the response, though the content still passes through its backend.
Helicone-Omit-Request: true
Helicone-Omit-Response: true
Bear Lumen can only import what Helicone records, so check in Helicone that requests sent with these headers still show token counts before you rely on them for cost.
Create a secret API key
Bear Lumen only reads from Helicone. Helicone serves its query API only to keys that also carry write permission, so the key needs read and write access even though Bear Lumen never writes anything.
- Sign in to Helicone in the region your organization uses and open Settings, then API Keys. In the US region that page is us.helicone.ai/settings/api-keys.
- Create a new key with read and write permission. A read-only key is refused by Helicone's query API, and the connection test says so.
- Copy the key. A write-only key, which Helicone gives a
pk-prefix, cannot read requests and is refused.
Connect in Bear Lumen
- In the Bear Lumen app, open Settings, Integrations and choose Helicone from the usage sources.
- Paste the key. Then choose the region where you created the key: US (
api.helicone.ai) or EU (eu.api.helicone.ai). - 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 Helicone 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 Helicone 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 | Helicone-User-Id, stored by Helicone as the request's user id. | 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 Helicone custom properties, which you set with Helicone-Property-<Name> headers. Map a property by its name, the part after the prefix: the header Helicone-Property-Feature is the property feature. Helicone stores the names of header-set properties in lower case, so Bear Lumen matches property names without regard to case, and Feature works too. A request that carries a customer id, a feature and one more property looks like this:
Helicone-User-Id: customer-4821
Helicone-Property-Feature: support-chat
Helicone-Property-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 Helicone 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 Helicone can finish recording a request a little after it happened. For Helicone 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 Helicone 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. Helicone'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 Helicone. The two copies are not deduplicated. Use one source per workload, for example the connector for traffic that already runs through Helicone 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 Helicone region. Disconnecting and reconnecting the same Helicone region 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 Helicone |
|---|---|---|
| Authentication failed | Syncing stops and the connector shows Needs attention. It is not retried automatically. | The key was deleted, mistyped, or created in the other region. Create a new key in the same Helicone organization and region, and rotate it on the connector page. To read another organization or region, disconnect and connect again with its key. |
| Permission denied | Syncing stops and the connector shows Needs attention. It is not retried automatically. | The key cannot query requests. Write-only keys (prefix pk-) and read-only keys are both refused by Helicone's query API. Create a secret key with read and write permission. |
| Unsupported version | Syncing stops and the connector shows Needs attention. It is not retried automatically. | Does not apply to Helicone's hosted US and EU regions. |
| 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. | Helicone's API did not answer. Nothing to do unless it persists; syncing resumes on its own. |
| 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. |