Tags

Tags let you attach custom key:value metadata to requests sent through Kimchi. Once attached, tags appear in Analytics, where you can filter usage and cost data by any combination of tags.

Tag format

Tags follow a key:value format validated against the following pattern:

^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?:[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$

Constraint	Limit
Format	`key:value`
Key length	1–64 characters
Value length	1–64 characters
Tags per request	10 maximum
First/last character	Must be alphanumeric (`a-z`, `A-Z`, `0-9`)
Interior characters	Letters, numbers, hyphens (`-`), underscores (`_`), dots (`.`)

📘
Valid examples: env:prod, team:ml-platform, experiment.v2:run-42, region:us.west.1

Attaching tags to requests

Request body

curl -X POST https://llm.kimchi.dev/openai/v1/chat/completions \
  -H "Authorization: Bearer $KIMCHI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m2.7",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "tags": ["env:prod", "team:ml", "feature:onboarding"]
  }'

HTTP headers

curl -X POST https://llm.kimchi.dev/openai/v1/chat/completions \
  -H "Authorization: Bearer $KIMCHI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Tags: env:prod,team:ml,feature:onboarding" \
  -d '{
    "model": "minimax-m2.7",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Header	Description
`X-Tags`	Primary tag header
`X-LiteLLM-Tags`	Alternative header for LiteLLM compatibility

When tags are provided in both headers and the request body, Kimchi merges and deduplicates them.

Tag query API

Three endpoints let you look up tags used across your organization. All endpoints require authentication via the X-API-Key header and return at most 50 results.

Endpoint	Description
`SearchTagKeys`	Returns tag keys used in your organization, ranked by popularity. Supports filtering by key prefix.
`SearchTagValues`	Returns values for a specific tag key, ranked by popularity. Supports filtering by value prefix.
`SearchTags`	Returns full `key:value` tag combinations, ranked by popularity. Supports filtering by key prefix.

CEL filter syntax

The GenerateAnalytics and GenerateLatestInferenceSummaries API endpoints accept a filter field that uses CEL (Common Expression Language) syntax to narrow results by tag.

Expression	Meaning	Example
`tags["key"] == "value"`	Match requests with an exact `key:value` tag	`tags["env"] == "prod"`
`"key" in tags`	Match requests that have any value for the key	`"env" in tags`
`expr1 && expr2`	Combine multiple conditions with AND	`tags["env"] == "prod" && tags["team"] == "ml"`

Expressions can be combined freely. For example, to match production requests that have any experiment tag:

tags["env"] == "prod" && "experiment" in tags

Filtering analytics by tags

After you start sending tagged requests, use the Tags filter on the Analytics page to break down usage and cost data by tag.