Tags

Attach key:value metadata to requests, then filter or compare usage, cost, and analytics by project, environment, team, or another reporting dimension.

Tags attach custom key:value metadata to requests sent through Kimchi. Use the Usage and Analytics filters to report on those requests by project, environment, experiment, cost center, or another dimension you choose.

For chargeback reporting, apply a consistent key and set of values to every relevant request. For example, use a tag such as project:checkout to group requests for one project.

Tags do not change native ownership. A team:platform tag does not set a request's native team ID, change a user's membership, or assign a team budget. A user:alice tag creates a reporting grouping; it does not authenticate Alice or assign native user ownership.

How tags get onto requests

Tags reach a request in one of two ways, and both surfaces feed the same console filters:

  • Coding sessions: the Kimchi TUI resolves default tags from your environment, repository, and global config. It applies them to every request in the session. See Tag sessions by project to set this up.
  • Direct API requests: pass tags in the request body or an HTTP header. See Tag API requests.

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])?$
ConstraintLimit
Formatkey:value
Key length1-64 characters
Value length1-64 characters
Tags per request10 maximum
First/last characterMust be alphanumeric (a-z, A-Z, 0-9)
Interior charactersLetters, numbers, hyphens (-), underscores (_), dots (.), and @ inside a direct API tag value

The gateway allows @ inside a value, not at its start or end.

The /tags command in Kimchi TUI rejects @ in tag keys and values. To reuse a tag in direct API requests and Coding sessions, avoid @ so both surfaces accept it.

📘

Valid examples: env:prod, team:capers, persona:non-grata, project.v2:run-42, user:[email protected] through the gateway

Manage tags with the /tags command

Inside a Kimchi Coding session, use the /tags command to view and change the active tags:

CommandWhat it does
/tagsList all currently active tags
/tags add key:value ...Add one or more tags
/tags remove tag ...Remove one or more user-defined tags
/tags clearRemove all user-defined tags at once

The TUI saves tags added with /tags add to ~/.config/kimchi/tags.json. They persist across sessions until you remove them with /tags remove or /tags clear.

📘

The /tags command cannot modify static tags from the KIMCHI_TAGS environment variable. It can remove only user-defined tags that you added with /tags add.

Limits and automatic tags

RuleBehavior
10 tags per requestThe cap counts resolved defaults plus session tags. /tags add fails with an error when the set is full.
Automatic model: tagKimchi adds model:{model_id} to every request automatically. Kimchi reserves this tag and excludes it from the 10-tag cap.
Automatic phase: tagKimchi adds phase:{phase} only while a session's phase is active (explore, plan, build, review, research). Kimchi reserves this tag and excludes it from the cap.

Tag query API

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

EndpointDescription
SearchTagKeysReturns tag keys used in your organization, ranked by popularity. Supports filtering by key prefix.
SearchTagValuesReturns values for a specific tag key, ranked by popularity. Supports filtering by value prefix.
SearchTagsReturns 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.

ExpressionMeaningExample
tags["key"] == "value"Match requests with an exact key:value tagtags["env"] == "prod"
"key" in tagsMatch requests that have any value for the key"env" in tags
expr1 && expr2Combine multiple conditions with ANDtags["env"] == "prod" && tags["team"] == "capers"

The following expression combines two conditions. It matches production requests that have any experiment tag:

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

Filter and compare tags

In Usage → By user and Usage → By team, use Tags to select the key:value tags to include. The Teams filter remains a separate native-team control.

Select tags

Open Usage → By tag. Select at least two full key:value tags under Select tags to compare.

Compare the tags

Select Compare, then use Requests, Tokens, and Cost to inspect the comparison.

The Tags filter in Usage with phase and model tags and a selected model value

A request with multiple selected tags can appear under more than one row. Do not add the individual rows to calculate an organization total. See Compare tags.

For programmatic chargeback reporting, use Generate Cost Breakdown by Dimension with dimension=BREAKDOWN_DIMENSION_TAG_KEY and your chosen tagKey. This groups records by a custom tag without changing native ownership.

Related resources


Did this page help you?