Schedules Overview

Schedules define on-call rotations. They automatically rotate team members on a daily or weekly cadence and are referenced by relay rules to notify the current on-call user.

Schedule Types

Daily Rotation

Rotates every day at a specified time:

const schedule = await client.schedule.create({
  name: "Daily On-Call",
  relayId: "rly_abc123",
  type: "daily",
  startDay: "monday", // Not used for daily schedules
  startTime: "09:00", // Rotates at 9:00 AM every day
  externalKey: "daily-oncall", // Idempotent - safe to re-run
});

Weekly Rotation

Rotates every week on a specified day and time:

const schedule = await client.schedule.create({
  name: "Weekly On-Call",
  relayId: "rly_abc123",
  type: "weekly",
  startDay: "monday", // Rotates every Monday
  startTime: "09:00", // at 9:00 AM
  externalKey: "weekly-oncall", // Idempotent - safe to re-run
});

Schedule Members

Add team members to the schedule to participate in the rotation:

await client.schedule.addMember(schedule.id, {
  userId: "usr_alice",
});

await client.schedule.addMember(schedule.id, {
  userId: "usr_bob",
});

Members rotate in the order they were added. The first member added is assignment #1, the second is #2, etc.

On-Call Status

Check who is currently on-call:

const onCall = await client.schedule.getOnCall(schedule.id);
console.log(`${onCall.email} is on-call (assignment #${onCall.assignmentNumber})`);

Assignments

View upcoming or past assignments to understand the rotation:

// Get the next 14 days of assignments
const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "days",
  count: 14,
});

assignments.forEach((assignment) => {
  console.log(
    `Assignment ${assignment.assignmentNumber}: ${assignment.userId} from ${assignment.startDate} to ${assignment.endDate}`
  );
});

Schedule Overrides

Overrides let you temporarily replace the on-call user without changing the rotation itself. They’re useful for vacation coverage, sick days, or mid-shift handoffs.

An override applies to a specific time window (up to 30 days) and expires automatically. While active, getOnCall returns the override user instead of the regularly scheduled person. Overrides cannot overlap on the same schedule.

const override = await client.schedule.createOverride(schedule.id, {
  userId: "usr_bob",
  startAt: "2025-03-15T09:00:00.000Z",
  endAt: "2025-03-22T09:00:00.000Z",
  reason: "Covering for Alice — vacation",
});

See Schedule Overrides for the full management guide.

Common Use Cases

Basic On-Call Rotation

Create a simple weekly rotation:

const relay = await client.relay.create({
  name: "Production Alerts",
});

const schedule = await client.schedule.create({
  name: "Weekly On-Call",
  relayId: relay.id,
  type: "weekly",
  startDay: "monday",
  startTime: "09:00",
});

await client.schedule.addMember(schedule.id, { userId: "usr_alice" });
await client.schedule.addMember(schedule.id, { userId: "usr_bob" });
await client.schedule.addMember(schedule.id, { userId: "usr_charlie" });

await client.relay.rules.create(relay.id, {
  name: "Notify on-call engineer",
  ruleType: "schedule_notify",
  config: {
    scheduleId: schedule.id,
  },
});

Multi-Tier On-Call

Create primary and backup schedules:

const primarySchedule = await client.schedule.create({
  name: "Primary On-Call",
  relayId: relay.id,
  type: "weekly",
  startDay: "monday",
  startTime: "09:00",
});

const backupSchedule = await client.schedule.create({
  name: "Backup On-Call",
  relayId: relay.id,
  type: "weekly",
  startDay: "monday",
  startTime: "09:00",
});

await client.relay.rules.create(relay.id, {
  name: "Notify primary first",
  order: 1,
  ruleType: "schedule_notify",
  config: { scheduleId: primarySchedule.id },
});

await client.relay.rules.create(relay.id, {
  name: "Escalate to backup",
  order: 2,
  ruleType: "schedule_notify",
  config: { scheduleId: backupSchedule.id },
});

Follow-the-Sun Rotation

Create different schedules for different time zones:

const usSchedule = await client.schedule.create({
  name: "US Business Hours",
  relayId: relay.id,
  type: "daily",
  startDay: "monday",
  startTime: "08:00", // 8 AM US time
});

const euSchedule = await client.schedule.create({
  name: "EU Business Hours",
  relayId: relay.id,
  type: "daily",
  startDay: "monday",
  startTime: "08:00", // 8 AM EU time
});