llmburn
Track what each of your users costs you in Gemini calls, and cut them off before they cost too much.
pip install "llmburn[gemini]"
import llmburn
llmburn.init() # writes to ./llmburn.db
llmburn.instrument() # from here on, every Gemini call is recorded
Then tag the calls with the user who made them:
with llmburn.track(user_id=user.id, plan=user.plan, feature="summarize"):
resp = client.models.generate_content(model="gemini-3.5-flash-lite", contents=prompt)
And see who's spending what:
$ llmburn report --by user --last 30d
LLM spend by user, the last 30 days
USER CALLS INPUT TOK OUTPUT TOK COST
--------------------------------------------
u_4821 9,412 9,412,000 3,100,000 $41.20
u_0193 2,201 2,201,000 600,000 $6.75
u_7730 310 150,000 40,000 $0.42
--------------------------------------------
TOTAL 11,923 $48.37
(Example data.) If you charge a flat monthly price, the top row is the one to look at.
How it works
instrument() wraps the google-genai SDK's generate_content methods. Each call goes to Google exactly as before; when the response comes back, llmburn reads the token counts Google already includes in it (usage_metadata), prices them, and writes one row to SQLite. Your code and the response are untouched.
The token counts are Google's own numbers, not an estimate. Prices come from a bundled table (prices.json) that handles thinking tokens, cached input, the >200k-token tier on Pro models, and price changes Google has announced with a date.
If anything inside llmburn fails (unknown model, locked database), it logs a warning and your request carries on. The one exception is a budget you set to block, below.
Tagging
track() works as a with block or a decorator, and tags nest:
with llmburn.track(user_id=user.id, plan="pro"):
write_cover_letter(job) # inherits user_id and plan
@llmburn.track(feature="cover_letter")
def write_cover_letter(job): ... # adds feature
Tags are per thread and per async task, so concurrent requests in Flask or FastAPI don't mix up users. Calls with no tags are still recorded, as (untagged).
A Flask route looks like this:
@app.post("/rewrite")
def rewrite():
with llmburn.track(user_id=g.user.id, plan=g.user.plan, feature="rewrite"):
resp = client.models.generate_content(model="gemini-3.5-flash-lite", contents=...)
return {"text": resp.text}
Budgets
You can cap spending per user, for the whole app, or both. The check runs before the request is sent, so a blocked call never reaches Google and isn't billed.
llmburn.init(
budget_per_user="$2/day",
budget_total="$50/day",
on_limit="block",
)
try:
with llmburn.track(user_id=g.user.id):
resp = client.models.generate_content(...)
except llmburn.BudgetExceeded as e:
if e.is_total:
return {"error": "AI features are paused for today."}, 503
return {"error": "You've reached today's limit."}, 429
on_limit can be:
"block": raisellmburn.BudgetExceeded"downgrade": send the call to a cheaper model instead (downgrade_to="gemini-3.5-flash-lite")"warn": log it and let the call through
Periods are /hour, /day, /week or /month (30 days), measured as a rolling window, so $2/day means the last 24 hours. Untagged calls only count toward budget_total.
Reports
llmburn report # by user, last 7 days
llmburn report --by feature --last 30d
llmburn report --by model --last 24h
llmburn report --by plan --last all
llmburn report --db sqlite:///path/to/llmburn.db --limit 50
Or from Python:
store = llmburn.init()
for row in store.totals(by="user_id"):
print(row.key, row.calls, row.cost_usd)
What's stored
One row per call: timestamp (UTC), user_id, plan, feature, model, input/output/cached tokens, and cost in USD. Prompts and responses are never stored.
Supported
google-genai method |
|
|---|---|
client.models.generate_content |
yes |
client.models.generate_content_stream |
yes, one row when the stream ends |
client.aio.models.generate_content |
yes |
client.aio.models.generate_content_stream |
yes |
Limitations
- Gemini only for now. OpenAI and Anthropic are next.
- Prices ship with the package. When Google changes them, you need a new llmburn release until automatic updates land.
- Budgets can overshoot by a call or two when several requests for the same user arrive at once.
- Text models only. Image, audio, TTS and live models aren't priced yet; their calls are skipped with a warning.
Planned
- OpenAI and Anthropic SDKs
- Flask, FastAPI and Django middleware that sets
user_idfor you - Automatic price-table updates
- A hosted dashboard with revenue per customer next to cost
Python 3.9+. No required dependencies. MIT license.
Metadata
Release files for llmburn 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llmburn-0.1.0.tar.gz | 18.0 kB | Without provenance | Details for llmburn-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llmburn-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for llmburn-0.1.0-py3-none-any.whl |
Total release size: 33.1 kB
Release files / llmburn-0.1.0.tar.gz
| Download URL | llmburn-0.1.0.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
506547530e81878aa198d1cb6cbeb44cd290131a513bdd893ac8dae08ea1c7a6
|
|
BLAKE2b-256 checksum How to use checksums |
e2ed54ca3c5ea157def0900990dcbecd2fd0d9679e07063728140f9168f4507d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.7
|
Release files / llmburn-0.1.0-py3-none-any.whl
| Download URL | llmburn-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
20335bb8a53f3637e6fcb56855c5b6df4b5a38e87fe8751499fb42d0f67bce94
|
|
BLAKE2b-256 checksum How to use checksums |
6e641dd61197d8cad9ee58465af822eaae7e895ce605c35b27b5efd520a839c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.7
|
Security for llmburn 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.