Proxy setup and tagging

Start the proxy

burnlens start runs a local proxy on 127.0.0.1:8420. It forwards each request to the real provider — streaming included — and records what the call cost on the way through.

burnlens start
burnlens start --port 9000 --host 127.0.0.1
burnlens start --otel        # also export to an OpenTelemetry collector
burnlens start --no-env      # do not print the env var exports on startup

It binds to loopback by default. Exposing it on 0.0.0.0 puts an unauthenticated forwarder holding your provider keys on the network — if you need that, put it behind something that authenticates, and read virtual keys first.

Point your SDK at it

Each provider gets its own path. For most, one environment variable is the whole integration and your application code does not change at all.

export OPENAI_BASE_URL=http://127.0.0.1:8420/proxy/openai
export ANTHROPIC_BASE_URL=http://127.0.0.1:8420/proxy/anthropic

Google, Mistral and Together have no environment variable

Their SDKs do not read a base URL from the environment. Setting one does nothing, and this failure is silent: your traffic goes straight to the provider while the dashboard shows nothing and you conclude BurnLens is broken.

For Google, call the patch helper once at startup, before your first request:

from burnlens.patch import patch_google
patch_google()

For Mistral and Together, pass the proxy path explicitly where you construct the client. The parameter name is the SDK's, not ours — check yours, it is usually base_url or server_url:

client = SomeClient(api_key=..., base_url="http://127.0.0.1:8420/proxy/mistral")

Azure deployment routing and Bedrock bearer-token auth have provider-specific detail — PROVIDERS.md covers both. If nothing appears after setup, burnlens doctor checks the proxy, the database and provider reachability in one pass.

Attribute spend with tags

A bill tells you the model. Tags tell you the feature. Three request headers attribute any call to any dimension you care about, and BurnLens strips all three before the request reaches the provider.

X-BurnLens-Tag-Feature: checkout-summariser
X-BurnLens-Tag-Team: platform
X-BurnLens-Tag-Customer: acme-corp

Set them wherever your SDK lets you add default headers, and every call from that client is attributed without further work:

client = OpenAI(default_headers={"X-BurnLens-Tag-Feature": "checkout-summariser"})

Team and customer tags are what per-team budgets and per-customer spend reports are keyed on, so tag before you set a budget rather than after. burnlens customers and burnlens budgets read them directly.

For agent and CI work, burnlens run <command> wraps a child process and tags its traffic with the surrounding git context automatically.

What the proxy sends where

Request and response bodies go to the provider you were already calling, and nowhere else. BurnLens records model, token counts, timing, status and tag values. If you enable cloud sync, that metadata — including tag values — is uploaded to your workspace; bodies are not, and no setting turns that on. How data is handled.

Next

Metering on its own does not stop anything. To make the proxy refuse a call that would breach a limit, see budgets and hard caps.