feat(alerts): add scheduleStartAt + scheduleOffsetMinutes

packages/api/openapi.json

@@ -169,6 +169,20 @@
             "$ref": "#/components/schemas/AlertInterval",
             "example": "1h"
           },
+          "scheduleOffsetMinutes": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).",
+            "nullable": true,
+            "example": 2
+          },
+          "scheduleStartAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.",
+            "nullable": true,
+            "example": "2026-02-08T10:00:00.000Z"
+          },
           "source": {
             "$ref": "#/components/schemas/AlertSource",
             "example": "tile"

packages/api/src/controllers/alerts.ts

@@ -22,6 +22,8 @@ export type AlertInput = {
   source?: AlertSource;
   channel: AlertChannel;
   interval: AlertInterval;
+  scheduleOffsetMinutes?: number;
+  scheduleStartAt?: string | null;
   thresholdType: AlertThresholdType;
   threshold: number;
 
@@ -46,9 +48,21 @@ export type AlertInput = {
 };
 
 const makeAlert = (alert: AlertInput, userId?: ObjectId): Partial<IAlert> => {
+  const hasScheduleStartAt = Object.prototype.hasOwnProperty.call(
+    alert,
+    'scheduleStartAt',
+  );
+
   return {
     channel: alert.channel,
     interval: alert.interval,
+    ...(alert.scheduleOffsetMinutes != null && {
+      scheduleOffsetMinutes: alert.scheduleOffsetMinutes,
+    }),
+    ...(hasScheduleStartAt && {
+      scheduleStartAt:
+        alert.scheduleStartAt == null ? null : new Date(alert.scheduleStartAt),
+    }),
     source: alert.source,
     threshold: alert.threshold,
     thresholdType: alert.thresholdType,

packages/api/src/models/alert.ts

@@ -44,6 +44,8 @@ export interface IAlert {
   id: string;
   channel: AlertChannel;
   interval: AlertInterval;
+  scheduleOffsetMinutes?: number;
+  scheduleStartAt?: Date | null;
   source?: AlertSource;
   state: AlertState;
   team: ObjectId;
@@ -88,6 +90,15 @@ const AlertSchema = new Schema<IAlert>(
       type: String,
       required: true,
     },
+    scheduleOffsetMinutes: {
+      type: Number,
+      min: 0,
+      required: false,
+    },
+    scheduleStartAt: {
+      type: Date,
+      required: false,
+    },
     channel: Schema.Types.Mixed, // slack, email, etc
     state: {
       type: String,

packages/api/src/routers/api/alerts.ts

@@ -12,6 +12,7 @@ import {
   getAlertsEnhanced,
   updateAlert,
 } from '@/controllers/alerts';
+import AlertSchema, { IAlert } from '@/models/alert';
 import { alertSchema, objectIdSchema } from '@/utils/zod';
 
 const router = express.Router();
@@ -67,6 +68,8 @@ router.get('/', async (req, res, next) => {
           ..._.pick(alert, [
             '_id',
             'interval',
+            'scheduleOffsetMinutes',
+            'scheduleStartAt',
             'threshold',
             'thresholdType',
             'state',
@@ -96,7 +99,7 @@ router.post(
       return res.sendStatus(403);
     }
     try {
-      const alertInput = req.body;
+      const alertInput = req.body as unknown as IAlert;
       return res.json({
         data: await createAlert(teamId, alertInput, userId),
       });

packages/api/src/routers/external-api/v2/alerts.ts

@@ -105,6 +105,18 @@ import { alertSchema, objectIdSchema } from '@/utils/zod';
  *         interval:
  *           $ref: '#/components/schemas/AlertInterval'
  *           example: "1h"
+ *         scheduleOffsetMinutes:
+ *           type: integer
+ *           minimum: 0
+ *           description: Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).
+ *           nullable: true
+ *           example: 2
+ *         scheduleStartAt:
+ *           type: string
+ *           format: date-time
+ *           description: Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.
+ *           nullable: true
+ *           example: "2026-02-08T10:00:00.000Z"
  *         source:
  *           $ref: '#/components/schemas/AlertSource'
  *           example: "tile"

packages/api/src/tasks/checkAlerts/__tests__/checkAlerts.test.ts

@@ -32,6 +32,7 @@ import * as checkAlert from '@/tasks/checkAlerts';
 import {
   doesExceedThreshold,
   getPreviousAlertHistories,
+  getScheduledWindowStart,
   processAlert,
 } from '@/tasks/checkAlerts';
 import {
@@ -122,6 +123,45 @@ describe('checkAlerts', () => {
     });
   });
 
+  describe('getScheduledWindowStart', () => {
+    it('should align to the default interval boundary when offset is 0', () => {
+      const now = new Date('2024-01-01T12:13:45.000Z');
+      const windowStart = getScheduledWindowStart(now, 5, 0);
+
+      expect(windowStart).toEqual(new Date('2024-01-01T12:10:00.000Z'));
+    });
+
+    it('should align to an offset boundary when schedule offset is provided', () => {
+      const now = new Date('2024-01-01T12:13:45.000Z');
+      const windowStart = getScheduledWindowStart(now, 5, 2);
+
+      expect(windowStart).toEqual(new Date('2024-01-01T12:12:00.000Z'));
+    });
+
+    it('should keep previous offset window until the next offset boundary', () => {
+      const now = new Date('2024-01-01T12:11:59.000Z');
+      const windowStart = getScheduledWindowStart(now, 5, 2);
+
+      expect(windowStart).toEqual(new Date('2024-01-01T12:07:00.000Z'));
+    });
+
+    it('should align windows using scheduleStartAt as an absolute anchor', () => {
+      const now = new Date('2024-01-01T12:13:45.000Z');
+      const scheduleStartAt = new Date('2024-01-01T12:02:30.000Z');
+      const windowStart = getScheduledWindowStart(now, 5, 0, scheduleStartAt);
+
+      expect(windowStart).toEqual(new Date('2024-01-01T12:12:30.000Z'));
+    });
+
+    it('should prioritize scheduleStartAt over offset alignment', () => {
+      const now = new Date('2024-01-01T12:13:45.000Z');
+      const scheduleStartAt = new Date('2024-01-01T12:02:30.000Z');
+      const windowStart = getScheduledWindowStart(now, 5, 2, scheduleStartAt);
+
+      expect(windowStart).toEqual(new Date('2024-01-01T12:12:30.000Z'));
+    });
+  });
+
   describe('Alert Templates', () => {
     // Create a mock metadata object with the necessary methods
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion

packages/api/src/tasks/checkAlerts/index.ts

@@ -64,6 +64,95 @@ export const doesExceedThreshold = (
   return false;
 };
 
+const normalizeScheduleOffsetMinutes = ({
+  alertId,
+  scheduleOffsetMinutes,
+  windowSizeInMins,
+}: {
+  alertId: string;
+  scheduleOffsetMinutes: number | undefined;
+  windowSizeInMins: number;
+}) => {
+  if (scheduleOffsetMinutes == null) {
+    return 0;
+  }
+
+  if (!Number.isFinite(scheduleOffsetMinutes)) {
+    return 0;
+  }
+
+  const normalized = Math.max(0, Math.floor(scheduleOffsetMinutes));
+  if (normalized < windowSizeInMins) {
+    return normalized;
+  }
+
+  const scheduleOffsetInMins = normalized % windowSizeInMins;
+  logger.warn(
+    {
+      alertId,
+      scheduleOffsetMinutes,
+      normalizedScheduleOffsetMinutes: scheduleOffsetInMins,
+      windowSizeInMins,
+    },
+    'scheduleOffsetMinutes is greater than or equal to the interval and was normalized',
+  );
+  return scheduleOffsetInMins;
+};
+
+const normalizeScheduleStartAt = ({
+  alertId,
+  scheduleStartAt,
+}: {
+  alertId: string;
+  scheduleStartAt: unknown;
+}) => {
+  if (scheduleStartAt == null) {
+    return undefined;
+  }
+
+  const scheduleStartAtDate =
+    scheduleStartAt instanceof Date
+      ? scheduleStartAt
+      : new Date(scheduleStartAt as string);
+  const scheduleStartAtMs = scheduleStartAtDate.getTime();
+  if (Number.isFinite(scheduleStartAtMs)) {
+    return scheduleStartAtDate;
+  }
+
+  logger.warn(
+    {
+      alertId,
+      scheduleStartAt,
+    },
+    'Invalid scheduleStartAt value detected, ignoring start time schedule',
+  );
+  return undefined;
+};
+
+export const getScheduledWindowStart = (
+  now: Date,
+  windowSizeInMins: number,
+  scheduleOffsetMinutes = 0,
+  scheduleStartAt?: Date,
+) => {
+  if (scheduleStartAt != null) {
+    const windowSizeMs = windowSizeInMins * 60 * 1000;
+    const elapsedMs = Math.max(0, now.getTime() - scheduleStartAt.getTime());
+    const windowCountSinceStart = Math.floor(elapsedMs / windowSizeMs);
+    return new Date(
+      scheduleStartAt.getTime() + windowCountSinceStart * windowSizeMs,
+    );
+  }
+
+  if (scheduleOffsetMinutes <= 0) {
+    return roundDownToXMinutes(windowSizeInMins)(now);
+  }
+
+  const shiftedNow = fns.subMinutes(now, scheduleOffsetMinutes);
+  const roundedShiftedNow = roundDownToXMinutes(windowSizeInMins)(shiftedNow);
+  return fns.addMinutes(roundedShiftedNow, scheduleOffsetMinutes);
+};
+
 const fireChannelEvent = async ({
   alert,
   alertProvider,
@@ -126,6 +215,12 @@ const fireChannelEvent = async ({
       dashboardId: dashboard?.id,
       groupBy: alert.groupBy,
       interval: alert.interval,
+      ...(alert.scheduleOffsetMinutes != null && {
+        scheduleOffsetMinutes: alert.scheduleOffsetMinutes,
+      }),
+      ...(alert.scheduleStartAt != null && {
+        scheduleStartAt: alert.scheduleStartAt.toISOString(),
+      }),
       message: alert.message,
       name: alert.name,
       savedSearchId: savedSearch?.id,
@@ -227,6 +322,7 @@ const getAlertEvaluationDateRange = (
   hasGroupBy: boolean,
   nowInMinsRoundDown: Date,
   windowSizeInMins: number,
+  scheduleStartAt?: Date,
 ) => {
   // Calculate date range for the query
   // Find the latest createdAt among all histories for this alert
@@ -248,10 +344,16 @@ const getAlertEvaluationDateRange = (
     previousCreatedAt = previous?.createdAt;
   }
 
+  const rawStartTime = previousCreatedAt
+    ? previousCreatedAt.getTime()
+    : fns.subMinutes(nowInMinsRoundDown, windowSizeInMins).getTime();
+  const clampedStartTime =
+    scheduleStartAt == null
+      ? rawStartTime
+      : Math.max(rawStartTime, scheduleStartAt.getTime());
+
   return calcAlertDateRange(
-    previousCreatedAt
-      ? previousCreatedAt.getTime()
-      : fns.subMinutes(nowInMinsRoundDown, windowSizeInMins).getTime(),
+    clampedStartTime,
     nowInMinsRoundDown.getTime(),
     windowSizeInMins,
   );
@@ -388,7 +490,43 @@ export const processAlert = async (
   const { alert, source, previousMap } = details;
   try {
     const windowSizeInMins = ms(alert.interval) / 60000;
-    const nowInMinsRoundDown = roundDownToXMinutes(windowSizeInMins)(now);
+    const scheduleStartAt = normalizeScheduleStartAt({
+      alertId: alert.id,
+      scheduleStartAt: alert.scheduleStartAt,
+    });
+    if (scheduleStartAt != null && now < scheduleStartAt) {
+      logger.info(
+        {
+          alertId: alert.id,
+          now,
+          scheduleStartAt,
+        },
+        'Skipped alert check because scheduleStartAt is in the future',
+      );
+      return;
+    }
+
+    const scheduleOffsetMinutes = normalizeScheduleOffsetMinutes({
+      alertId: alert.id,
+      scheduleOffsetMinutes: alert.scheduleOffsetMinutes,
+      windowSizeInMins,
+    });
+    if (scheduleStartAt != null && scheduleOffsetMinutes > 0) {
+      logger.info(
+        {
+          alertId: alert.id,
+          scheduleStartAt,
+          scheduleOffsetMinutes,
+        },
+        'scheduleStartAt is set; scheduleOffsetMinutes is ignored for window alignment',
+      );
+    }
+    const nowInMinsRoundDown = getScheduledWindowStart(
+      now,
+      windowSizeInMins,
+      scheduleOffsetMinutes,
+      scheduleStartAt,
+    );
     const hasGroupBy = alert.groupBy && alert.groupBy.length > 0;
 
     // Check if we should skip this alert check based on last evaluation time
@@ -400,6 +538,8 @@ export const processAlert = async (
           now,
           alertId: alert.id,
           hasGroupBy,
+          scheduleOffsetMinutes,
+          scheduleStartAt,
         },
         `Skipped to check alert since the time diff is still less than 1 window size`,
       );
@@ -411,6 +551,7 @@ export const processAlert = async (
       !!hasGroupBy,
       nowInMinsRoundDown,
       windowSizeInMins,
+      scheduleStartAt,
     );
 
     const chartConfig = getChartConfigFromAlert(