Enable Tag Filtering

Overview

Tag Filtering allows LLMGrid to route requests to model deployments based on matching tags. This is useful when multiple deployments share the same public model name but serve different purposes, such as:

free vs paid
standard vs premium
region:us vs region:eu
Provider-specific deployments
Team-specific deployments
Workload-specific deployments

When Tag Filtering is enabled, LLMGrid evaluates the tags associated with the incoming request and uses them to determine which model deployments are eligible for routing.

Enable Tag Filtering

To enable Tag Filtering:

Sign in to the LLMGrid console.
Select the appropriate Tenant.
Navigate to Router Settings.
Open the Loadbalancing tab.
Locate Enable Tag Filtering.
Turn on Enable Tag Filtering.
Select Save Changes.

Once enabled, request tags can participate in model deployment selection.

Tag Filtering should be enabled only after the model deployments that participate in tag-based routing have been assigned appropriate tags.

How Tag Filtering Works

Consider three deployments that expose the same public model:

Deployment	Public Model	Tag
Deployment A	`enterprise-chat`	`free`
Deployment B	`enterprise-chat`	`paid`
Deployment C	`enterprise-chat`	`default`

An application always requests enterprise-chat. The tag determines which deployment pool is eligible.

{
  "model": "enterprise-chat",
  "tags": ["free"]
}

The example above routes the request toward deployments tagged free.

Send a Tagged Request

Tags can be included directly in the request body.

Route to `free`

curl -X POST "https://api.llmgrid.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LLMGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "enterprise-chat",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ],
    "tags": ["free"]
  }'

Route to `paid`

curl -X POST "https://api.llmgrid.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LLMGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "enterprise-chat",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ],
    "tags": ["paid"]
  }'

Passing Tags Through Metadata

Tags can also be provided within request metadata.

curl -X POST "https://api.llmgrid.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LLMGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "enterprise-chat",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ],
    "metadata": {
      "tags": ["paid"]
    }
  }'

Passing Tags Through a Request Header

Tags can also be supplied through the x-litellm-tags request header. Multiple tags are comma-separated.

curl -X POST "https://api.llmgrid.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LLMGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-litellm-tags: paid,region:us" \
  -d '{
    "model": "enterprise-chat",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

Default Tag

Use the reserved default tag to provide a deployment pool for requests that do not specify routing tags.

Deployment	Tag
Deployment A	`free`
Deployment B	`paid`
Deployment C	`default`

When a default deployment is available, it provides the candidate pool for an untagged request.

Configure a deliberate default deployment when applications may send requests without routing tags.

Negation Tags

Prefix a tag with ! to exclude deployments carrying that exact tag.

curl -X POST "https://api.llmgrid.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LLMGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "enterprise-chat",
    "messages": [{"role": "user", "content": "Hello"}],
    "metadata": {
      "tags": ["!provider:anthropic"]
    }
  }'

All remaining eligible deployments can participate in routing.

Exclude Multiple Deployment Groups

{
  "metadata": {
    "tags": [
      "!provider:anthropic",
      "!provider:openai"
    ]
  }
}

Negation tags use exact matching and are not regular expressions.

Required Tags

Prefix a tag with & when a deployment must contain that tag to remain eligible.

{
  "metadata": {
    "tags": [
      "&reasoning_type:high",
      "&region:us"
    ]
  }
}

The request can only be routed to a deployment containing both required tags.

Tag Types

Tag	Purpose	Example
Plain tag	Select matching deployments	`premium`
Required tag	Require a deployment to contain the tag	`&region:us`
Negation tag	Exclude deployments containing the tag	`!provider:anthropic`

These conditions can be combined.

{
  "metadata": {
    "tags": [
      "&reasoning_type:high",
      "provider:anthropic",
      "provider:openai",
      "!region:eu"
    ]
  }
}

No Matching Deployment

Tag constraints can eliminate all available deployments. If no eligible deployment remains, LLMGrid rejects the request because the routing requirements cannot be satisfied. This behavior is particularly important when tags represent mandatory requirements.

Fail-Open Behavior

Advanced configurations can allow a model group to fail open when caller-supplied required or negation tags eliminate all candidate deployments. Instead of failing the request, routing can return to the configured default deployment pool.

Use fail-open carefully. A default deployment might not satisfy the original caller-supplied ! or & constraint.

Do not use fail-open behavior when a tag represents a mandatory compliance, provider, security, or regional requirement.

Team-Based Tag Routing

Tags can also be associated with teams.

Team A → teamA
Team B → teamB

Model deployments can use corresponding tags:

Deployment A → teamA
Deployment B → teamB

Virtual Keys associated with those teams can inherit routing context, allowing LLMGrid to direct team traffic to the appropriate deployment group. This is useful for:

Department-specific deployments
Dedicated capacity
Customer-specific model pools
Business-unit isolation
Environment-specific routing

Recommended Tag Naming

Use structured tag names that remain understandable as the number of deployments grows.

tier:free
tier:paid
region:us
region:eu
provider:openai
provider:anthropic
team:finance
team:engineering
workload:batch
workload:interactive
reasoning_type:high

For environments where tags are also used for reporting or cost attribution, consider explicitly identifying routing tags.

route:tier:premium
route:region:us
project:customer-support
environment:production

Verify Tag Routing

After enabling Tag Filtering:

Send a request with a known routing tag.
Open Request Logs.
Locate the request.
Verify the model and deployment selected for the request.
Repeat using a different tag.

For example, test free followed by paid and verify that LLMGrid selects the expected deployment pool.

Troubleshooting

Tags do not affect routing

Verify that:

Enable Tag Filtering is enabled in Router Settings.
Tags have been assigned to the applicable model deployments.
The request tag exactly matches a deployment tag.
The requested public model has eligible tagged deployments.
The Virtual Key is authorized to use the requested model.

Untagged requests are not routing as expected

Verify that the applicable model group has a deployment tagged default.

Required tags cause requests to fail

A required tag such as &region:us must exist on an eligible deployment. If no deployment satisfies all required tags, the request cannot be routed.

Negation tags remove all deployments

Review the ! tags supplied with the request. Multiple exclusions may leave no eligible deployment.

Best Practices

Configure deployment tags before enabling Tag Filtering.
Use consistent namespaces such as provider:, region:, tier:, team:, and workload:.
Configure a default deployment for requests that do not send routing tags.
Use & for requirements that must all be satisfied.
Use ! to explicitly remove deployment groups.
Avoid using caller-controlled tags alone as a security or compliance boundary.
Use team and Virtual Key policies for administrator-controlled routing requirements.
Test tag routing before enabling it for production workloads.
Use Request Logs to validate routing outcomes.

Getting Started

Administration

Developer Docs

Enable Tag Filtering

Overview

Enable Tag Filtering

How Tag Filtering Works

Send a Tagged Request

Route to `free`

Route to `paid`

Passing Tags Through Metadata

Passing Tags Through a Request Header

Default Tag

Negation Tags

Exclude Multiple Deployment Groups

Required Tags

Tag Types

No Matching Deployment

Fail-Open Behavior

Team-Based Tag Routing

Recommended Tag Naming

Verify Tag Routing

Troubleshooting

Tags do not affect routing

Untagged requests are not routing as expected

Required tags cause requests to fail

Negation tags remove all deployments

Best Practices

​Overview

​Enable Tag Filtering

​How Tag Filtering Works

​Send a Tagged Request

​Route to free

​Route to paid

​Passing Tags Through Metadata

​Passing Tags Through a Request Header

​Default Tag

​Negation Tags

​Exclude Multiple Deployment Groups

​Required Tags

​Tag Types

​No Matching Deployment

​Fail-Open Behavior

​Team-Based Tag Routing

​Recommended Tag Naming

​Verify Tag Routing

​Troubleshooting

​Tags do not affect routing

​Untagged requests are not routing as expected

​Required tags cause requests to fail

​Negation tags remove all deployments

​Best Practices

Overview

Enable Tag Filtering

How Tag Filtering Works

Send a Tagged Request

Route to `free`

Route to `paid`

Passing Tags Through Metadata

Passing Tags Through a Request Header

Default Tag

Negation Tags

Exclude Multiple Deployment Groups

Required Tags

Tag Types

No Matching Deployment

Fail-Open Behavior

Team-Based Tag Routing

Recommended Tag Naming

Verify Tag Routing

Troubleshooting

Tags do not affect routing

Untagged requests are not routing as expected

Required tags cause requests to fail

Negation tags remove all deployments

Best Practices