> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# LiteLLM Proxy

> Wrap a client for your LiteLLM Proxy to meter and gate calls, with the cost LiteLLM computed for each call.

## Set up

LiteLLM Proxy can be self-hosted or cloud-hosted by LiteLLM. Either way, each proxy has its own address, so the SDK cannot recognize it automatically. Pass the LiteLLM recipe with your proxy's base URL:

```typescript theme={null}
import OpenAI from 'openai';
import { litellmRecipe } from '@stigg/agent-sdk-js';

const litellm = stigg.wrap(
  new OpenAI({ baseURL: 'https://litellm.example.com', apiKey: process.env.LITELLM_KEY }),
  { recipe: litellmRecipe({ baseUrl: 'https://litellm.example.com' }) },
);

await litellm.chat.completions.create({
  model: 'gpt-5',   // a model group from your proxy's config
  messages,
  stiggContext: { customerId: 'customer-acme', entitlement: { currencyId: 'credits' } },
});
```

To change how `cost` is counted, set `unitsPerDollar` on the recipe.

### `litellmRecipe` options

| Option | Default | Description |
| - | - | - |
| `baseUrl` | | Required. Your proxy's URL, used to recognize the client. |
| `unitsPerDollar` | `1000000` (millionths of a dollar) | How many `cost` units make one US dollar. LiteLLM prices calls in dollars, and the recipe reports `cost` as a whole number, so a small unit keeps cheap calls from rounding up. |
| `modelDimension` | `model` | The dimension the deployment that served the call is reported under. |
| `estimate` | `() => 1` | The requested usage of the check before the call. See [Enforcing a limit on cost](/documentation/ai-agents/access-enforcement#enforcing-a-limit-on-cost). |

## What is reported

LiteLLM Proxy is a gateway, self-hosted or cloud-hosted: one API in OpenAI's format in front of many model providers. Every response includes a `usage` object in OpenAI's format with the token counts. LiteLLM also prices each call itself and returns that price in the `x-litellm-response-cost` response header. The wrapper reads both and reports them to Stigg as the metrics below. For details, see LiteLLM's [cost tracking](https://docs.litellm.ai/docs/proxy/cost_tracking) and [response headers](https://docs.litellm.ai/docs/proxy/response_headers) docs.

| Method | Event name |
| - | - |
| `chat.completions.create` | `litellm.chat.completions.create` |
| `responses.create` | `litellm.responses.create` |

**Chat Completions**

| Metric | What it counts |
| - | - |
| `prompt_tokens` | Input tokens, **including** cached tokens |
| `completion_tokens` | Output tokens |
| `cached_tokens` | Input tokens served from the cache |
| `total_tokens` | All input and output tokens, as reported by the vendor |
| `cost` | The price LiteLLM computed for the call, read from the `x-litellm-response-cost` header, in micro-dollars by default. Non-streaming calls only. |

**Responses**

| Metric | What it counts |
| - | - |
| `input_tokens` | Input tokens, **including** cached tokens |
| `output_tokens` | Output tokens |
| `cached_tokens` | Input tokens served from the cache |
| `total_tokens` | All input and output tokens, as reported by the vendor |
| `cost` | The price LiteLLM computed for the call, read from the `x-litellm-response-cost` header, in micro-dollars by default. Non-streaming calls only. |

Cached tokens are counted **inside** `prompt_tokens` and `input_tokens`. If you price both the input metric and `cached_tokens`, cached tokens are charged twice. `total_tokens` includes all the token counts above, so price the total or the parts, never both.

Each event also carries:

| Reported | What it is |
| - | - |
| `model` dimension | The deployment that served the call. |

> [!WARNING]
>
> Response headers are sent before the model generates anything, so a **streamed** LiteLLM call cannot carry a cost. Streamed calls report tokens only. If you meter `cost`, use non-streaming calls or also price the token metrics.

Every usage field the vendor returns is also included, with a `raw.` prefix. See [How usage is reported](/documentation/ai-agents/usage-metering#how-usage-is-reported).


## Related topics

- [Meter LLM gateway spend](/guides/ai-agents/meter-llm-gateway-spend.md)
- [Usage metering](/documentation/ai-agents/usage-metering.md)
- [Bring your own vendor](/documentation/ai-agents/providers/custom.md)
- [Set budgets for AI agents](/guides/ai-agents/set-budgets-for-ai-agents.md)
- [Meter usage from your own gateway](/guides/ai-agents/meter-usage-from-your-own-gateway.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.