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 audit 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 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 about a minute on other replicas (keys refresh from storage in the background).

​
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:
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.

​
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.
  • Request log — label chips per request, filterable with the label query param on GET /admin/usage/log.
  • Audit logs — recorded under data.labels on each entry (requires LOGGING_ENABLED=true).
  • API keys page — each key’s labels are listed alongside its user path.

​
Defaults

Labelling is on by default and costs nothing until you configure a tagging rule or create a labelled key. Requests without labels are tracked as before.