Tags and labels configuration

Tags and labels are short string values attached to alerts and configuration. Unit Oncall maintains them as a per-Organization master so they auto-complete in the UI and stay consistent across resources. You normally do not create tag or label master entries by hand — they are populated automatically as alerts arrive and as configuration is saved.

This page explains how the master is populated, what status and source mean, and which Unit Oncall feature uses tags versus labels.

Tags vs labels

Reserved tags that start with _ (such as _notify:*) are interpreted by Unit Oncall itself (for example to override notification routing). They are never added to the tag master.

Master entry fields

Each entry in the tag or label master has the following fields. They are read-only from the API: you can list and suggest them, but you do not edit them directly.

Status: confirmed vs candidate

• confirmed — the value is stable enough to suggest in autocomplete. An entry becomes confirmed via one of three paths:
  1. It is in key:value form with a stable value (for example service:checkout or region:us-east) when first seen.
  2. A user adds it manually through saved configuration.
  3. It was a candidate and has been observed repeatedly: after 3 observations the background upsert promotes it to confirmed automatically.
• candidate — the value has been observed but is not yet trusted. Free-form tags from incoming webhooks (anything that is not key:value, plus key:value pairs whose value looks like a timestamp, UUID, IP, or large number) start as candidates and remain so until the auto-promotion threshold described above is reached.

Only confirmed entries appear in the suggestion API. Candidate entries are tracked so you can review them but they are not auto-completed.

Source: webhook vs manual

• webhook — Unit Oncall extracted the value from an incoming alert payload via its transformation rule.
• manual — A user added the value by saving configuration. Manual entries from Bundle Settings, Schedule labels, and routing rule conditions are immediately confirmed.

Lifecycle

Candidate entries that go unused are pruned automatically. By default, candidates that have not been seen for 30 days are removed by a background job. Confirmed entries are never automatically removed.

If a tag name's usage_count rises while its last_seen_at keeps moving forward, that is a signal you may want to promote it to a confirmed name (typically by reshaping it into a key:value form in your transformation rule).

Validation rules (for values that get added to the master)

• Empty values are not added.
• Values longer than 200 characters are not added.
• Values that start with _ are reserved for Unit Oncall and are rejected for both tags and labels (the backend isValidTagLabel check is shared between Tag Master and Label Master).
• Values are normalized: leading/trailing whitespace is trimmed and characters are lower-cased before storage.
• Manual additions are always stored as confirmed. Webhook-sourced values are stored as confirmed only when they are key:value with a stable value; otherwise they are stored as candidate.

Examples

A confirmed tag added by a transformation rule that emits service:<name>. usage_count is frozen at the value the entry had at the moment it became confirmed (typically 0 for tags confirmed on first observation):

{
  "id": 101,
  "organization_id": 42,
  "name": "service:checkout",
  "status": "confirmed",
  "source": "webhook",
  "usage_count": 0,
  "last_seen_at": "2026-06-05T01:00:00Z",
  "created_at": "2026-06-01T09:30:00Z"
}

A candidate tag automatically extracted from a free-form alert payload. The next observation will be the 3rd one and will promote the entry to confirmed, freezing usage_count at 3:

{
  "id": 102,
  "organization_id": 42,
  "name": "host-12ab",
  "status": "candidate",
  "source": "webhook",
  "usage_count": 2,
  "last_seen_at": "2026-06-04T22:14:00Z",
  "created_at": "2026-06-04T22:10:00Z"
}

A confirmed label added when a Schedule was saved with labels: ["env:prod"]. Manual entries are confirmed from the start and usage_count is not incremented afterwards:

{
  "id": 201,
  "organization_id": 42,
  "name": "env:prod",
  "status": "confirmed",
  "source": "manual",
  "usage_count": 0,
  "last_seen_at": "2026-06-05T00:00:00Z",
  "created_at": "2026-06-05T00:00:00Z"
}

Related

• Bundle Settings — tags here are matched against the tag master.
• Schedule — labels are stored in the label master.
• Transformation Rule — produces the tags and labels seen by the master.
• Routing Rule — conditions can reference tag and label values.