​
Overview

Escalation rules define automatic escalation behavior for overdue or stalled actions. Rules are configured per board and specify time thresholds, escalation targets, and notification preferences. A background cron job evaluates rules periodically and escalates qualifying actions.

​
Get Rules

Retrieve escalation rules for a board.

GET /api/trpc/escalation.getRules?input={"json":{"boardId":"brd_01HXK5..."}}

Response:

{
  "result": {
    "data": {
      "json": {
        "rules": [
          {
            "id": "esc_01HXK5QJBN3YZXM8KJP2RSNV4C",
            "boardId": "brd_01HXK5...",
            "name": "Overdue high-priority escalation",
            "enabled": true,
            "conditions": {
              "priority": ["critical", "high"],
              "overdueDays": 3,
              "statuses": ["open", "in_progress"]
            },
            "escalation": {
              "targetLevel": 1,
              "escalateToRole": "manager",
              "escalateToUserId": null
            },
            "notification": {
              "channels": ["in_app", "email"],
              "message": "Action \"{action.title}\" is overdue by {overdue.days} days and requires attention."
            },
            "createdAt": "2026-02-10T10:00:00.000Z"
          },
          {
            "id": "esc_01HXK6...",
            "boardId": "brd_01HXK5...",
            "name": "Critical 24h escalation to director",
            "enabled": true,
            "conditions": {
              "priority": ["critical"],
              "overdueDays": 1,
              "statuses": ["open"]
            },
            "escalation": {
              "targetLevel": 2,
              "escalateToRole": null,
              "escalateToUserId": "usr_01HXK7..."
            },
            "notification": {
              "channels": ["in_app", "email", "sms"],
              "message": "CRITICAL: \"{action.title}\" unresolved for {overdue.days} day(s)."
            },
            "createdAt": "2026-02-10T10:05:00.000Z"
          }
        ]
      }
    }
  }
}

​
Set Rules

Create or update escalation rules for a board. This replaces all existing rules.

POST /api/trpc/escalation.setRules

Request:

{
  "json": {
    "boardId": "brd_01HXK5...",
    "rules": [
      {
        "name": "Level 1 — Manager escalation",
        "enabled": true,
        "conditions": {
          "priority": ["critical", "high"],
          "overdueDays": 3,
          "statuses": ["open", "in_progress"]
        },
        "escalation": {
          "targetLevel": 1,
          "escalateToRole": "manager"
        },
        "notification": {
          "channels": ["in_app", "email"],
          "message": "Action \"{action.title}\" is {overdue.days} days overdue."
        }
      },
      {
        "name": "Level 2 — Director escalation",
        "enabled": true,
        "conditions": {
          "priority": ["critical"],
          "overdueDays": 7,
          "statuses": ["open", "in_progress"]
        },
        "escalation": {
          "targetLevel": 2,
          "escalateToUserId": "usr_01HXK7..."
        },
        "notification": {
          "channels": ["in_app", "email", "sms"],
          "message": "URGENT: \"{action.title}\" has been overdue for {overdue.days} days."
        }
      }
    ]
  }
}

​
Rule Fields

FieldTypeRequiredDescription
namestringYesRule name (1-200 characters)
enabledbooleanYesWhether the rule is active
conditions.prioritystring[]YesPriority levels that trigger this rule
conditions.overdueDaysnumberYesDays overdue before escalation fires
conditions.statusesstring[]YesAction statuses that qualify
escalation.targetLevelnumberYesEscalation level (1, 2, 3…)
escalation.escalateToRolestringNoRole to escalate to (manager, director, vp)
escalation.escalateToUserIdstringNoSpecific user to escalate to
notification.channelsstring[]YesNotification channels: in_app, email, sms
notification.messagestringYesMessage template (supports variables)

​
Template Variables

VariableDescription
{action.title}Title of the escalated action
{action.id}ID of the escalated action
{action.url}Full URL to the action
{action.assignee}Name of the current assignee
{action.priority}Priority level
{overdue.days}Number of days overdue
{board.name}Name of the board

setRules replaces all existing rules for the board. To update a single rule, fetch all rules with getRules, modify the desired rule, and send the full list back.

​
Auto-Escalation Cron

The auto-escalation cron endpoint is called by the system scheduler to evaluate all active escalation rules and escalate qualifying actions.

POST /api/cron/escalation

Headers:

Authorization: Bearer <CRON_SECRET>

Response:

{
  "processed": 142,
  "escalated": 3,
  "errors": 0,
  "details": [
    {
      "actionId": "act_01HXK5...",
      "ruleId": "esc_01HXK5...",
      "fromLevel": 0,
      "toLevel": 1,
      "escalatedTo": "usr_01HXK6..."
    }
  ]
}

The cron endpoint is secured with a separate CRON_SECRET token and is not accessible with regular user Bearer tokens. In production, this is invoked every 15 minutes by the task scheduler.

Was this page helpful?

ActionsChecklists