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

# Enable Tag Filtering

> Enable tag-based routing to route requests to model deployments based on request and deployment tags.

## 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:

1. Sign in to the LLMGrid console.
2. Select the appropriate **Tenant**.
3. Navigate to **Router Settings**.
4. Open the **Loadbalancing** tab.
5. Locate **Enable Tag Filtering**.
6. Turn on **Enable Tag Filtering**.
7. 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.

```json theme={null}
{
  "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`

```bash theme={null}
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`

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```text theme={null}
Team A → teamA
Team B → teamB
```

Model deployments can use corresponding tags:

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
route:tier:premium
route:region:us
project:customer-support
environment:production
```

***

## Verify Tag Routing

After enabling Tag Filtering:

1. Send a request with a known routing tag.
2. Open **Request Logs**.
3. Locate the request.
4. Verify the model and deployment selected for the request.
5. 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:

1. **Enable Tag Filtering** is enabled in **Router Settings**.
2. Tags have been assigned to the applicable model deployments.
3. The request tag exactly matches a deployment tag.
4. The requested public model has eligible tagged deployments.
5. 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.


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