llmburn
Track what each of your users costs you in OpenAI, Anthropic and Gemini calls, and cut them off before they cost too much.
pip install "llmburn[openai]" # or [anthropic], [gemini], [all]
import llmburn
llmburn.init() # writes to ./llmburn.db
llmburn.instrument() # from here on, every OpenAI, Anthropic and 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.chat.completions.create(
model="gpt-6-luna",
messages=[{"role": "user", "content": 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 create methods of whichever official SDKs are installed: openai, anthropic and google-genai. Each call goes to the provider exactly as before. When the response comes back, llmburn reads the token counts the provider already includes in it, prices them, and writes one row to SQLite. Your code and the response are untouched.
The token counts are the provider's own numbers, not an estimate. Prices come from a bundled table (prices.json) that handles reasoning tokens, caching, long-prompt tiers and price changes a provider 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. Errors from the provider itself (a bad key, a model name the provider doesn't accept) reach your code unchanged.
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.messages.create(
model="claude-haiku-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": request.json["text"]}],
)
return {"text": resp.content[0].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 the provider and isn't billed. One budget covers all three SDKs: a user who spent their limit on Claude is blocked on GPT too.
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.chat.completions.create(...)
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="gpt-6-luna"). Pick a model from the same provider as your calls. A Gemini call can't be sent to an OpenAI model."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
| SDK | Methods | Streaming |
|---|---|---|
openai |
chat.completions.create, responses.create (and the .stream() helpers, which use them) |
yes |
anthropic |
messages.create, messages.stream |
yes |
google-genai |
models.generate_content, models.generate_content_stream |
yes |
Async clients work the same way. A stream is recorded once, as one row, when it ends: when you read it to the end, close it, or leave its with block. For OpenAI chat streams, llmburn asks for the token count with include_usage and hides the extra chunk that comes back, so your code sees the same chunks as before.
Limitations
- Prices ship with the package. When a provider 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.
- Standard-tier prices only. Batch, Flex, priority and regional pricing aren't applied.
- Text generation only. Image, audio and embedding calls aren't tracked, and models without a price are skipped with a warning.
- OpenAI's
.parse()helpers and.with_raw_responsearen't tracked yet.
Planned
- 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.2.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.2.0.tar.gz | 33.1 kB | Without provenance | Details for llmburn-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llmburn-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for llmburn-0.2.0-py3-none-any.whl |
Total release size: 56.1 kB
Release files / llmburn-0.2.0.tar.gz
| Download URL | llmburn-0.2.0.tar.gz |
|---|---|
| Size | 33.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a97c1625eb06a1c8f6a8c76b9d7a0a84f6977f4bd41366ee0cac96c55f6e1142
|
|
BLAKE2b-256 checksum How to use checksums |
e0e9103ccc6ff28922310a0b3f21946a97499caf824c98c0a359ccfc56710ca5
|
| 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.2.0-py3-none-any.whl
| Download URL | llmburn-0.2.0-py3-none-any.whl |
|---|---|
| Size | 23.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0236d868f4d322bf25a6758e79b06777f1335095670280206a34a090e22b25a9
|
|
BLAKE2b-256 checksum How to use checksums |
1c5010b2bd80eb8578397f7c9b6d4997f227d10dfea8658ae15d41342717a5d5
|
| 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.2.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.