> 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 in real time by registering Revenium as a proxy callback. Revenium connects to your existing LiteLLM proxy — it does not host LiteLLM. The callback runs inside your proxy and reports each call to Revenium as it happens.

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

* **Proxy callback (this page)** — real-time metering. Every call through the proxy is reported to Revenium as it completes. 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](/integrations/provider-integrations.md#litellm).

## What you need

* A LiteLLM proxy you operate, with a `config.yaml` you can edit and restart.
* A Revenium metering API key.
* Python available in the environment that runs your proxy.

## 1. Install the callback

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. Register the callback in your proxy config

Add the Revenium callback to `litellm_settings` in your proxy `config.yaml`:

```yaml
litellm_settings:
  callbacks: ["revenium_middleware.litellm.proxy.middleware.proxy_handler_instance"]
```

## 3. Set the metering key

Provide your Revenium metering API key to the proxy environment:

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

Then restart the proxy so it loads the callback.

## 4. Send a test transaction to confirm capture

Send one request through your proxy and confirm it appears in Revenium. This is the step that tells you exactly what your proxy captures — the callback follows what your LiteLLM version logs, so 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."}]
  }'
```

Within a minute the call appears in your Revenium metering data. If it does not, confirm the callback line is present in `config.yaml`, the metering key is set in the proxy environment, and the proxy was restarted after the change.

## 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
```

## What the callback captures

The callback meters calls that pass through your proxy, in real time, covering every model and provider your proxy routes to. What is captured follows what your LiteLLM version logs — use the test transaction above to confirm coverage for your specific request formats.

{% hint style="info" %}
**LiteLLM configuration note.** Proxy callbacks fire on the proxy's standard call path. They do **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, confirm capture with a test transaction before relying on the callback.
{% endhint %}

## Choose one metered path per workload

If a workload is already metered another way — for example Claude Code reporting its own usage over OpenTelemetry — meter it in **one** place. Two metered writers for the same calls report the usage twice, because they submit independently with no shared transaction identifier. Pick the proxy callback **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](/integrations/provider-integrations.md#litellm) for billed data is always safe alongside real-time metering.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.