Skip to main content

Overview

Labels tag every request for attribution: which team, feature, job, or environment produced the traffic. A request can be labelled two ways, and both can apply at once:
  • Tagging headers — labels extracted from configured HTTP headers on each request.
  • API key labels — labels bound to a managed API key, applied to every request authenticated with it.
Labels from both sources are merged and de-duplicated. They are recorded on usage entries and request log entries, and power the by-label usage breakdown in the dashboard.

API key labels

Assign labels when creating a key in the admin dashboard: API Keys -> Create API Key -> Labels GoModel dashboard API Keys page with a Labels column showing chips like env:demo, team:engineering, and priority:high for each key The API Keys page lists every managed key with its labels as chips next to its user path, so you can see attribution at a glance without opening each key. Click Edit Labels on a row to change them later. Or via the admin API:
Every request authenticated with that key carries those labels — no client changes needed. This is the simplest way to attribute traffic per team or service: issue each consumer its own labelled key. Labels can be changed later without rotating the key, in the dashboard (API Keys -> Edit Labels) or via the admin API:
The new list replaces the old one; send [] to remove all labels. Changes apply to new requests immediately on the instance that served the update and within a few seconds on other replicas sharing the database.

Tagging headers

Tagging rules name headers whose values carry labels. Manage them in the dashboard (Settings -> Tagging based on headers) or declare them as infrastructure-as-code: GoModel dashboard Settings page Tagging based on headers form with two header rows (X-Team, X-Environment) and prefix, delimiter, and do-not-pass-upstream fields Click Add Header, name the header your clients will send (for example X-Team), optionally set a prefix to trim and a delimiter, then Save Tagging Settings. Check Do not pass upstream for headers that should be stripped before the request reaches the provider.
config.yaml
Or with environment variables (an env entry replaces the whole YAML entry with the same header name; unset companion vars reset to defaults):
A client then labels a request like this:
Rules declared in config.yaml or env are read-only in the dashboard. Credential-bearing headers (Authorization, Cookie, API-key headers) are rejected as tagging sources. do_not_pass strips the header before forwarding on passthrough and realtime routes; translated routes never forward client headers anyway.

LiteLLM tags

Clients written for LiteLLM keep their tags with no configuration. GoModel reads them as labels from:
  • the x-litellm-tags header (comma-separated, as is a tags string);
  • a tags field in the body of /v1/chat/completions, /v1/responses, /v1/messages, and /v1/embeddings;
  • metadata.tags in those bodies, when it is a list.
GoModel removes them before the request reaches the provider, which would reject them: OpenAI has no tags parameter, and its metadata values must be strings. Other metadata keys pass through, and a string metadata.tags is left alone as ordinary OpenAI metadata. Request logs keep the body as the client sent it. One request contributes at most 32 distinct tags, counted across the header and both body fields in that order; the rest are dropped. Tags longer than 128 characters are dropped, not truncated. Dropped tags are still removed before the provider.
Clients choose their own tags, so any client can charge a label budget by naming its label. When label budgets must hold per team, turn LiteLLM tags off and label traffic with API key labels or tagging headers your proxy sets.
LiteLLM tags are on by default. Turn them off with:
config.yaml
When off, GoModel neither reads nor removes tags: requests reach the provider as the client sent them, so a provider that rejects tags returns its error.

Where labels show up

  • Usage dashboard — the usage page shows a by-label breakdown (GET /admin/usage/labels). A request with several labels counts once under each of them.
  • Usage log — label chips per request on the usage page, filterable with the label query param on GET /admin/usage/log.
  • Request logs — recorded under data.labels on each entry (request logging is enabled by default).
  • API keys page — each key’s labels are listed alongside its user path.
  • Budgets — a budget can be scoped to a label, capping the spend of every request carrying it. See Budgets.

Cost per pull request

To see what a pull request’s CI spends on models, send a label naming the PR, such as pr-1234, with every request its jobs make. The x-litellm-tags header works without configuration while LiteLLM tags are on (the default); with them off, configure a tagging header and send that instead. In GitHub Actions, set the label once for the job. Run the workflow on pull_request: other events, such as push, carry no PR number, so the label would be just pr-. GitHub does not pass repository secrets to pull requests from forks, so the job would have no key there: the if runs it only for branches in the repository.
.github/workflows/ci.yml
Then send it on each request:
Read the cost on the usage page: in Breakdown, set rows to Label and columns to Model or Period. Or filter any usage endpoint by the label for an exact figure:
  • A request with several labels counts once under each of them, so label rows overlap and can add up to more than the total.
  • The breakdown keeps the top rows (limit, at most 50) and folds the rest into Other. With many PRs, filter by label to get one PR’s cost rather than reading it from the pivot.

Defaults

Labelling is on by default and costs nothing until you configure a tagging rule, create a labelled key, or a client sends LiteLLM tags. Requests without labels are tracked as before.
Last modified on November 18, 2026