> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/integrations/litellm-proxy-setup.md).

# LiteLLM Proxy Setup

Meter a self-hosted LiteLLM proxy by adding the Revenium guardrail to your proxy configuration. The guardrail enforces your spending caps before each call reaches the provider, and meters the call after it completes. Revenium connects to your existing LiteLLM proxy; it does not host LiteLLM.

There are two ways to meter a LiteLLM proxy, and they suit different needs:

* **Proxy guardrail (this page)**: real-time metering and spending caps. Calls through the proxy are checked against your caps and reported to Revenium as they complete. The guardrail does not meter streamed `/v1/completions` calls. Requires a small change to your proxy configuration.
* **Provider integration**: scheduled sync with no code change. Revenium pulls spend and usage from your proxy's admin API on a schedule. See [Provider Integrations](https://docs.revenium.io/integrations/provider-integrations.md#litellm).

## What you need

* A LiteLLM proxy you operate, with a `config.yaml` you can edit and restart.
* LiteLLM 1.93.0 or newer. The SDK's `litellm-proxy` extra installs it.
* Python 3.10 or newer in the environment that runs your proxy.
* A Revenium metering API key (`rev_mk_`).

## 1. Install the guardrail

Install the Revenium SDK with the LiteLLM proxy extra into the same environment as your proxy:

```bash
pip install "revenium-python-sdk[litellm-proxy]"
```

## 2. Add the guardrail to your proxy config

Add a top-level `guardrails` block to your proxy `config.yaml`:

```yaml
guardrails:
  - guardrail_name: "revenium"
    litellm_params:
      guardrail: revenium_middleware.litellm.proxy.guardrail.ReveniumGuardrail
      mode:
        - "pre_call"    # budget enforcement
        - "post_call"   # usage metering
      default_on: true
```

{% hint style="warning" %}
`guardrails` is a **top-level** key. Nested under `litellm_settings`, it stops the proxy at startup. `mode` must be a **list** to enable both hooks; a single string restricts the guardrail to that one event type.
{% endhint %}

## 3. Set the metering key

Provide your Revenium metering API key (`rev_mk_`) to the proxy environment:

```bash
export REVENIUM_METERING_API_KEY="your_revenium_metering_api_key"
```

Then restart the proxy so it loads the guardrail.

## 4. Send a test transaction to confirm capture

Send one request through your proxy and confirm it appears in Revenium. A test transaction is the reliable way to confirm coverage for the request formats you use.

```bash
curl -s "$LITELLM_PROXY_URL/chat/completions" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-configured-model",
    "messages": [{"role": "user", "content": "Confirm metering is active."}]
  }'
```

The call then appears in your Revenium metering data with its cost, [within about a minute](https://docs.revenium.io/track-and-control-costs/data-freshness-and-provisional-figures.md#how-soon-usage-appears), because Revenium prices each call when it receives it (see [How Revenium Prices a Transaction](https://docs.revenium.io/track-and-control-costs/how-revenium-prices-a-transaction.md)). If it does not appear, confirm the `guardrails` block is at the top level of `config.yaml`, the metering key is set in the proxy environment, and the proxy was restarted after the change.

## Enforcing spending caps

Enforcement is opt-in: set `REVENIUM_CIRCUIT_BREAKER_ENABLED=true` in the proxy environment. The proxy then enforces the same caps as every other Revenium integration (see [Guardrail Enforcement](https://docs.revenium.io/track-and-control-costs/cost-controls.md)). A blocked call never reaches the provider, and the caller receives HTTP 429. Enforcement fails open and never delays a call. The guardrail checks each call against the caps it has already cached and refreshes them in the background, so caps it has cached keep blocking calls while Revenium cannot be reached. Only right after the proxy starts, before the first caps are fetched, do calls go through unchecked.

## Adding attribution

To attribute each call to a customer, product, agent, or task, pass Revenium metadata as request headers. Your application sends these alongside its normal proxy request:

```
x-revenium-trace-id
x-revenium-task-type
x-revenium-organization-name
x-revenium-product-name
x-revenium-agent
x-revenium-subscriber-email
x-revenium-subscriber-id
```

When a header is absent, the guardrail falls back to the metadata on the calling virtual key, except for the trace id, described below.

**Shared virtual keys.** By default a call is metered and checked against caps as the owner of the virtual key it used, which is right when each person has their own key. When several people share one key, have each client send `x-revenium-subscriber-email`, and optionally `x-revenium-subscriber-id`, naming the person making the call. Per-person and department caps are looked up by that email, so without it every call on a shared key counts against the key owner. The guardrail takes the header as the caller sends it, so a shared key trusts its users to name themselves. On a team with strict ingestion enabled, the email must belong to a registered user, or the call's record is rejected.

**Trace id.** The guardrail sets each call's trace id from the first of these that is present:

1. The `x-revenium-trace-id` header.
2. The LiteLLM session id your caller sent: the `x-litellm-session-id` or `x-litellm-trace-id` header, or `litellm_session_id` or `metadata.session_id` in the request body (`litellm_metadata.session_id` on `/v1/messages`).
3. Claude Code's `x-claude-code-session-id` header.

A call with none of these has no trace id. Calls you group into one LiteLLM session therefore appear as one trace in Revenium, and one Claude Code session is one trace. Two ids are never used: the per-call request id LiteLLM generates, which would make each call a trace of its own, and any session id LiteLLM generates itself under its `missing_session_id: generate` policy. The deprecated callback reads only `x-revenium-trace-id` and `x-claude-code-session-id`. Session grouping needs `revenium-python-sdk` 0.10.1 or newer.

**Trace type.** Set a default trace type for every call with `REVENIUM_TRACE_TYPE` on the proxy host, and override it per call with the `x-revenium-trace-type` header. The header wins. The other trace fields (environment, region, transaction name and trace name) follow the same pattern: a host setting as the default, and a matching header per call.

## Counting a Claude Code call once

If you run Claude Code through your proxy and also send Claude Code's own usage reporting to Revenium, the guardrail makes both records share one call identifier, so Revenium records each call once. This is on by default.

Four things have to be true for it to work:

* **LiteLLM 1.93.0 or newer.** The `litellm-proxy` extra installs this version. If your environment pins an older LiteLLM, the guardrail logs one warning at startup and each call is recorded twice.
* **`mode` includes `pre_call`.** The identifier is created in the pre-call hook. A `post_call`-only guardrail logs one warning at startup.
* **The Anthropic messages route, `/v1/messages`.** Other routes are left unchanged.
* **Both sides report to the same Revenium team.** The duplicate check is team-scoped.

**Point Claude Code at the proxy root, not at `/anthropic`.** Set `ANTHROPIC_BASE_URL` to the proxy's own base URL so Claude Code calls `<proxy>/v1/messages`:

```bash
export ANTHROPIC_BASE_URL=https://proxy.example.com
```

The identifier is created only on `/v1/messages`, not on LiteLLM's Anthropic pass-through at `<proxy>/anthropic/v1/messages`. If your Claude Code base URL ends in `/anthropic`, drop that suffix.

To opt out, set `REVENIUM_LITELLM_SHARED_CALL_ID=false` on the proxy host. Only the guardrail creates the shared identifier; a proxy running the deprecated callback alone never gets it.

## Choose one metered path per workload

If your proxy cannot use the shared call identifier (LiteLLM older than 1.93.0, a `post_call`-only mode, the `/anthropic` route, or the deprecated callback), meter each workload in **one** place. Two metered writers for the same calls, such as the proxy and Claude Code reporting its own usage over OpenTelemetry, then report the usage twice. Pick the proxy **or** the client telemetry for a given workload, and use the other only for the detail it uniquely adds.

Comparing what your provider **bills** against what Revenium **meters** is a separate, designed capability: billed and metered figures are held independently and shown side by side for reconciliation and coverage-health, never added together. Connecting your LiteLLM proxy as a [provider integration](https://docs.revenium.io/integrations/provider-integrations.md#litellm) for billed data is always safe alongside real-time metering.

## Migrating from the callback

The earlier `litellm_settings.callbacks` entry, `proxy_handler_instance`, is deprecated. It meters but never enforces a spending cap, and it logs a deprecation warning when the proxy starts. To migrate, delete the callbacks entry and add the `guardrails` block:

```diff
 litellm_settings:
-  callbacks: ["revenium_middleware.litellm.proxy.middleware.proxy_handler_instance"]
+
+guardrails:
+  - guardrail_name: "revenium"
+    litellm_params:
+      guardrail: revenium_middleware.litellm.proxy.guardrail.ReveniumGuardrail
+      mode: ["pre_call", "post_call"]
+      default_on: true
```

The same headers and the same metered fields carry over. Do not also list the guardrail in `litellm_settings.callbacks`, because every call would then be metered twice. While both are configured, a guardrail with `default_on: true` and `post_call` takes over metering from the callback, but delete the callbacks entry rather than relying on that.

{% hint style="info" %}
**LiteLLM configuration note.** This is a known issue for the callback path. The callback does **not** fire when the proxy runs with `use_chat_completions_url_for_anthropic_messages: true`, a LiteLLM setting with a known upstream issue ([BerriAI/litellm#27518](https://github.com/BerriAI/litellm/issues/27518), fix in [PR #27609](https://github.com/BerriAI/litellm/pull/27609)). If your proxy uses that setting with the guardrail, send a test transaction and confirm it appears in Revenium.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/integrations/litellm-proxy-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
