From cc85fe5921106d485d2f697dd9cfecddb6aa1ebf Mon Sep 17 00:00:00 2001 From: Ishaan Jaff Date: Wed, 25 Feb 2026 14:29:00 -0800 Subject: [PATCH] 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 * 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 * docs: use generic examples instead of specific company names Co-authored-by: Ishaan Jaff * 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 * 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 Co-authored-by: Ishaan Jaff Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- docs/my-website/docs/proxy/cost_tracking.md | 4 + docs/my-website/docs/proxy/request_tags.md | 128 +++++++++++++++++++- 2 files changed, 130 insertions(+), 2 deletions(-) diff --git a/docs/my-website/docs/proxy/cost_tracking.md b/docs/my-website/docs/proxy/cost_tracking.md index baebdf0f31..b1e5eae2a6 100644 --- a/docs/my-website/docs/proxy/cost_tracking.md +++ b/docs/my-website/docs/proxy/cost_tracking.md @@ -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) diff --git a/docs/my-website/docs/proxy/request_tags.md b/docs/my-website/docs/proxy/request_tags.md index c78c48229b..d6895d8971 100644 --- a/docs/my-website/docs/proxy/request_tags.md +++ b/docs/my-website/docs/proxy/request_tags.md @@ -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: + + + + +```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"] + }' +``` + + + + + +```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"] + } + }' +``` + + + + +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: + + + + +```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"] + } + }' +``` + + + + +```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"] + } + }' +``` + + + + +## 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