Guides · Concepts
How cost tracking works
Bear Lumen turns the AI calls you already make into cost you can attribute and analyze. Here is the mental model: what happens to a usage event, and the building blocks the rest of the docs assume.
The lifecycle of a usage event
- You send a usage event. Call
bear.track()from the SDK, or POST to/v1/usage-eventsdirectly, with a raw provider response or explicit token counts. - We detect the provider and model. From the response shape, Bear Lumen identifies the provider (OpenAI, Anthropic, Bedrock, Gemini, Mistral, Ollama, and more) and the exact model.
- We look up the rate card. The model's input and output prices come from the rate-card catalog, or from a custom rate you have set.
- We calculate the cost. Tokens multiplied by rates, server-side. Ingestion is asynchronous, so allow a short delay before the numbers appear.
- You read it back. Query the cost aggregated by model, provider, feature, end user, or any custom dimension you tagged, in the dashboard or over the API.
Ingestion is asynchronous
Events are queued and costed in the background, so allow a short delay after your first calls before the numbers appear. Backdated events are supported: an event_invoked_at more than 24 hours old is still accepted, just flagged as accepted_flagged.
Core building blocks
These are the nouns the rest of the docs use. For precise definitions of every term, see the glossary.
| Concept | What it is |
|---|---|
| Usage event | One tracked AI call (or non-token service): its model, provider, token counts, and any metadata you tag. |
| Provider | The AI vendor (OpenAI, Anthropic, and more). Auto-detected from the response you track. |
| Model | The specific model (gpt-4o, claude-3-5-sonnet). Priced by its rate card. |
| Rate card | The input and output price for a model. Use the public catalog, or set a custom rate for a negotiated or self-hosted model. |
| End user | Your customer, referenced by an external id. Attribute cost and margin to each one. |
| Dimension | Any custom attribute you tag events with (team, environment, feature). Group cost by it. |
| Margin | Revenue minus cost, when you report revenue. Turns raw cost into profitability. |
One event, many views
You track an event once. Because each event carries its model, provider, and whatever metadata you tag, the same events roll up many ways with no extra work: by model, by provider, by feature, by agent or workflow, per end user, and by any custom dimension. That is why tagging events well at track() time is the highest-leverage thing you do. Reading these breakdowns back is covered in the SDK and REST guides.