Skip to main content

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.

Requirements

Virtual Keys & a database should be set up. See Virtual Keys Setup.

Config Setup​

Set tags on model deployments in config.yaml:

config.yaml
model_list:
  - model_name: gpt-4
    litellm_params:
      model: azure/gpt-4-prod
      api_key: os.environ/AZURE_PROD_API_KEY
      api_base: https://prod.openai.azure.com/
      tags: ["AWS_IAM_PROD"]  # 👈 Tag for production

  - model_name: gpt-4-dev
    litellm_params:
      model: azure/gpt-4-dev
      api_key: os.environ/AZURE_DEV_API_KEY
      api_base: https://dev.openai.azure.com/
      tags: ["AWS_IAM_DEV"]  # 👈 Tag for development

Make Request​

Option 1: Use Config Tags (Automatic)​

Requests just specify the model - tags are automatically applied from config:

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"}]
  }'

Option 2: Use x-litellm-tags Header​

Pass tags dynamically via the x-litellm-tags header as a comma-separated string:

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:

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"]
  }'

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:

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"]
    }
  }'

Advanced: Custom Header Tracking​

Track spend using any custom header by adding it to your config:

litellm_settings:
  extra_spend_tag_headers:
    - "x-custom-header"
    - "x-customer-id"

Disable User-Agent tracking:

litellm_settings:
  disable_add_user_agent_to_request_tags: true

Spend Logs​

The tag from the model config appears in LiteLLM_SpendLogs:

{
  "request_id": "chatcmpl-abc123",
  "request_tags": ["AWS_IAM_PROD"],
  "spend": 0.002,
  "model": "gpt-4"
}