mirror of
https://github.com/tiennm99/litellm.git
synced 2026-07-12 09:05:33 +00:00
Proxy request tags docs (#22129)
* docs: document x-litellm-tags header and request body tags parameter - Add documentation for x-litellm-tags header (comma-separated or array) - Add documentation for tags in request body - Clarify that dynamic tags override config tags Co-authored-by: Ishaan Jaff <ishaan-jaff@users.noreply.github.com> * docs: consolidate tag documentation and improve cross-references - Make request_tags.md the single source of truth for all tag options - Add cross-reference from cost_tracking.md to request_tags.md - Document both direct tags and metadata.tags formats - Add key/team tag setup and custom header tracking to request_tags.md - Reduce duplication and make navigation clearer Co-authored-by: Ishaan Jaff <ishaan-jaff@users.noreply.github.com> * docs: use generic examples instead of specific company names Co-authored-by: Ishaan Jaff <ishaan-jaff@users.noreply.github.com> * docs: clarify x-litellm-tags header format is comma-separated string HTTP headers are always strings, not arrays. Remove misleading array format documentation for the header parameter. Co-authored-by: Ishaan Jaff <ishaan-jaff@users.noreply.github.com> * Update docs/my-website/docs/proxy/request_tags.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Ishaan Jaff <ishaan-jaff@users.noreply.github.com> Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
This commit is contained in:
Ishaan Jaff
@@ -326,6 +326,10 @@ See our [Swagger API](https://litellm-api.up.railway.app/#/Budget%20%26%20Spend%
|
||||
|
||||
## Custom Tags
|
||||
|
||||
:::tip See Full Request Tags Documentation
|
||||
For comprehensive documentation on all tag options including `x-litellm-tags` header, request body `tags`, and config-based tags, see the dedicated [Request Tags](./request_tags.md) page.
|
||||
:::
|
||||
|
||||
Requirements:
|
||||
|
||||
- Virtual Keys & a database should be set up, see [virtual keys](https://docs.litellm.ai/docs/proxy/virtual_keys)
|
||||
|
||||
@@ -1,9 +1,16 @@
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Request Tags for Spend Tracking
|
||||
|
||||
Add tags to model deployments to track spend by environment, AWS account, or any custom label.
|
||||
|
||||
Tags appear in the `request_tags` field of LiteLLM spend logs.
|
||||
|
||||
:::info Requirements
|
||||
Virtual Keys & a database should be set up. See [Virtual Keys Setup](./virtual_keys.md).
|
||||
:::
|
||||
|
||||
## Config Setup
|
||||
|
||||
Set tags on model deployments in `config.yaml`:
|
||||
@@ -27,7 +34,9 @@ model_list:
|
||||
|
||||
## Make Request
|
||||
|
||||
Requests just specify the model - tags are automatically applied:
|
||||
### Option 1: Use Config Tags (Automatic)
|
||||
|
||||
Requests just specify the model - tags are automatically applied from config:
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
|
||||
@@ -39,6 +48,120 @@ curl -X POST 'http://0.0.0.0:4000/chat/completions' \
|
||||
}'
|
||||
```
|
||||
|
||||
### Option 2: Use `x-litellm-tags` Header
|
||||
|
||||
Pass tags dynamically via the `x-litellm-tags` header as a comma-separated string:
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
|
||||
-H 'Authorization: Bearer sk-1234' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-litellm-tags: team-api,production,us-east-1' \
|
||||
-d '{
|
||||
"model": "gpt-4",
|
||||
"messages": [{"role": "user", "content": "Hello"}]
|
||||
}'
|
||||
```
|
||||
|
||||
Format: Comma-separated string (spaces are automatically trimmed): `"tag1,tag2,tag3"`
|
||||
|
||||
### Option 3: Use Request Body `tags`
|
||||
|
||||
Pass tags directly in the request body. Both formats are supported:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="direct" label="Direct tags Field">
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
|
||||
-H 'Authorization: Bearer sk-1234' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "gpt-4",
|
||||
"messages": [{"role": "user", "content": "Hello"}],
|
||||
"tags": ["team-api", "production", "us-east-1"]
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="metadata" label="Metadata Nested">
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
|
||||
-H 'Authorization: Bearer sk-1234' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "gpt-4",
|
||||
"messages": [{"role": "user", "content": "Hello"}],
|
||||
"metadata": {
|
||||
"tags": ["team-api", "production", "us-east-1"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The `tags` field must be an array of strings.
|
||||
|
||||
:::info
|
||||
When tags are provided via header or request body, they override any tags configured in the model deployment. If both header and body tags are provided, body tags take precedence.
|
||||
:::
|
||||
|
||||
## Set Tags on Keys or Teams
|
||||
|
||||
You can also set default tags at the API key or team level:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="key" label="Set on Key">
|
||||
|
||||
```bash
|
||||
curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
|
||||
-H 'Authorization: Bearer sk-1234' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"metadata": {
|
||||
"tags": ["customer-acme", "tier-premium"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="team" label="Set on Team">
|
||||
|
||||
```bash
|
||||
curl -L -X POST 'http://0.0.0.0:4000/team/new' \
|
||||
-H 'Authorization: Bearer sk-1234' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"metadata": {
|
||||
"tags": ["team-engineering", "department-ai"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Advanced: Custom Header Tracking
|
||||
|
||||
Track spend using any custom header by adding it to your config:
|
||||
|
||||
```yaml
|
||||
litellm_settings:
|
||||
extra_spend_tag_headers:
|
||||
- "x-custom-header"
|
||||
- "x-customer-id"
|
||||
```
|
||||
|
||||
**Disable User-Agent tracking:**
|
||||
|
||||
```yaml
|
||||
litellm_settings:
|
||||
disable_add_user_agent_to_request_tags: true
|
||||
```
|
||||
|
||||
## Spend Logs
|
||||
|
||||
The tag from the model config appears in `LiteLLM_SpendLogs`:
|
||||
@@ -54,5 +177,6 @@ The tag from the model config appears in `LiteLLM_SpendLogs`:
|
||||
|
||||
## Related
|
||||
|
||||
- [Spend Tracking Overview](cost_tracking.md)
|
||||
- [Spend Tracking Overview](cost_tracking.md) - Complete tutorial on tracking spend with tags
|
||||
- [Tag Budgets](tag_budgets.md) - Set budget limits per tag
|
||||
- [Virtual Keys Setup](virtual_keys.md) - Required for tag tracking
|
||||
|
||||
Reference in New Issue
Block a user