Custom Monitor States

Custom monitor states let you define org-wide states beyond the built-in Up, Down, and Degraded. This is useful when your monitors need to represent conditions like “Rate Limited”, “Maintenance Mode”, or “Partially Available”.

What Are Custom States?

Each custom state has the following properties:

Property	Description
Name	A human-readable label (e.g., “Rate Limited”).
Health Class	One of: healthy, degraded, or unhealthy.
Severity	The alert severity associated with this state.
Color	A display color used in the dashboard and status pages.

Custom states are defined at the organization level, so all monitors in the org share the same set of available states.

Built-in States

The three built-in states, Up, Degraded, and Down, cannot be deleted or renamed. They serve as the default states for all monitors.

Creating Custom States

1. Navigate to Settings > Monitor States.
2. Click New State.
3. Enter a name, select a health class, set the severity, and choose a color.
4. Click Save.

The new state is now available across all monitors in your organization.

Match Rules

Match rules are per-monitor rules that map HTTP response conditions to custom states. Rules are evaluated in order, and the first matching rule wins. If no rule matches, the monitor falls back to the default built-in state logic.

Configuring Match Rules

1. Open the monitor edit form.
2. Scroll to the Match Rules section.
3. Click Add Rule.
4. Define the condition and select the target state.
5. Drag rules to reorder them. The first match wins.
6. Click Save.

Match Rule Conditions

Condition Type	Options
Status Code	Exact match (e.g., 429) or range (e.g., 500-599).
Body Match	Contains, not_contains, or regex match against response body.
Header Match	Match a specific response header name and value.

You can combine multiple conditions in a single rule. All conditions in a rule must match for the rule to apply.

Example

Consider an API monitor where you want to distinguish rate limiting from backend failures:

1. Rule 1: If status code is 429, set state to “Rate Limited” (health class: degraded).
2. Rule 2: If status code is 503, set state to “Backend Issue” (health class: unhealthy).
3. Default: If no rules match, the standard Up/Down/Degraded logic applies.

With this configuration, your team gets precise visibility into the type of failure, not just that something is wrong.

Tip

Keep your rule list short and ordered from most specific to least specific. The first matching rule takes effect, so put narrow conditions (like exact status codes) before broad ones (like status code ranges).