Unit Oncall logo markUnit Oncall
Back to Home

Bundle Settings configuration

Bundle Settings control how Unit Oncall groups related alerts into a single Bundle within a Schedule. Each Bundle Settings entry applies to one tag set: incoming alerts that match the tag set are merged into the same Bundle while the bundling window is open, instead of producing separate notifications.

A Bundle Settings entry belongs to a Schedule, so create the Team and Schedule first. Multiple entries can coexist within a Schedule as long as each one targets a different tag set.

Fields

FieldTypeRequiredDefaultNotes
namestringYes—Bundle name. Cannot be empty. Up to 100 characters.
descriptionstringNo""Free-text description. Up to 500 characters.
enabledbooleanYestrueWhether this Bundle Settings entry is active. The default at creation is true but the field must be present in the request body.
tagsarrayYes—Tags that identify which incoming alerts join this Bundle. At least 1 tag required, up to 10 tags; duplicates are not allowed.
window_secondsnumberYes30How long the bundling window stays open, in seconds. Range: 10–300.
max_alerts_per_bundlenumberYes1000Maximum number of distinct alert fingerprints a single Bundle can hold. Range: 1–1000.
auto_resolve_on_infobooleanYestrueWhen an info severity alert arrives in the matching tag set, the Bundle is automatically resolved.
auto_expire_hoursnumberYes24After this many hours a Bundle that has not been closed is auto-expired. Range: 1–720 (up to 30 days).
cooldown_after_resolve_minutesnumberYes0Cooldown after a Bundle is resolved before a new Bundle for the same tag set can open. Range: 0–60.
cooldown_after_dismiss_minutesnumberYes5Cooldown after a Bundle is dismissed. Range: 0–60.

Validation rules

  • name is required and is rejected when empty or longer than 100 characters.
  • tags must contain at least one tag and at most ten. Duplicate tags within the same entry are rejected.
  • A Schedule cannot contain two enabled Bundle Settings entries that share the same tag set. Trying to save a duplicate tag set returns an error.
  • All numeric fields are rejected when they fall outside the ranges in the table above.
  • description is limited to 500 characters.

How bundling works

  1. An alert arrives at the Schedule (via a Webhook and any routing rules).
  2. Unit Oncall looks for an active Bundle whose tag set matches the alert and whose bundling window is still open.
  3. If a match is found, the alert is added to that Bundle. No new notification is sent for the additional alert beyond what the Bundle already tracks.
  4. If no Bundle is open, a new one is created. The bundling window stays open for window_seconds.
  5. When an info alert arrives for a Bundle and auto_resolve_on_info is on, the Bundle is closed.
  6. When a Bundle has been open longer than auto_expire_hours without being closed, it is auto-expired.
  7. After a Bundle closes, the cooldown fields determine how soon a new Bundle for the same tag set can open.

Examples

The API decodes the request body directly into BundleSettings; the JSON has the bundle fields at the top level (no spec wrapper).

A simple grouping for database alerts:

{
  "name": "Database alerts",
  "description": "Group DB alerts that share the db tag",
  "tags": ["db"],
  "enabled": true,
  "window_seconds": 30,
  "max_alerts_per_bundle": 1000,
  "auto_resolve_on_info": true,
  "auto_expire_hours": 24,
  "cooldown_after_resolve_minutes": 0,
  "cooldown_after_dismiss_minutes": 5
}

A wider window with a tighter fingerprint cap and longer cooldown:

{
  "name": "Region us-east bundle",
  "description": "Bundle all us-east alerts; keep the window open for 2 minutes",
  "tags": ["region:us-east", "env:prod"],
  "enabled": true,
  "window_seconds": 120,
  "max_alerts_per_bundle": 200,
  "auto_resolve_on_info": false,
  "auto_expire_hours": 6,
  "cooldown_after_resolve_minutes": 10,
  "cooldown_after_dismiss_minutes": 15
}

Related

  • Schedule — Bundle Settings belong to a Schedule and inherit its rotation and escalation.
  • Tags and labels — the values you put in tags are managed in the tag master.
  • Maintenance window — use this to suppress notifications during planned work, instead of widening the bundling window.