Schedule Assignments

Assignments show who is on-call during specific time periods. Use assignments to plan coverage, understand rotation patterns, and track historical data.

Understanding Assignments

Each assignment represents:

Assignment Number: The position in the rotation (1, 2, 3, etc.)
User ID: Who is on-call for this assignment
Start Date: When this assignment begins (ISO 8601 format)
End Date: When this assignment ends (ISO 8601 format)

Viewing Assignments

You can retrieve assignments in three ways:

By Number of Assignments

Get a specific number of upcoming assignments:

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

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

curl -X GET "https://api.beeps.dev/v0/schedule/sch_xyz789/assignments?type=assignments&count=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

By Number of Days

Get all assignments covering a specific number of days:

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

console.log(`Assignments covering next 14 days: ${assignments.length}`);

curl -X GET "https://api.beeps.dev/v0/schedule/sch_xyz789/assignments?type=days&count=14" \
  -H "Authorization: Bearer YOUR_API_KEY"

Until a Specific Date

Get all assignments up to a specific date:

const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "until",
  date: "2025-12-31T23:59:59.999Z", // Get assignments until end of year
});

console.log(`Assignments until 2025-12-31: ${assignments.length}`);

curl -X GET "https://api.beeps.dev/v0/schedule/sch_xyz789/assignments?type=until&date=2025-12-31T23:59:59.999Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

API Response

Response

{
  "assignments": [
    {
      "userId": "usr_alice",
      "startDate": "2025-01-20T09:00:00Z",
      "endDate": "2025-01-27T09:00:00Z",
      "assignmentNumber": 1
    },
    {
      "userId": "usr_bob",
      "startDate": "2025-01-27T09:00:00Z",
      "endDate": "2025-02-03T09:00:00Z",
      "assignmentNumber": 2
    },
    {
      "userId": "usr_charlie",
      "startDate": "2025-02-03T09:00:00Z",
      "endDate": "2025-02-10T09:00:00Z",
      "assignmentNumber": 3
    }
  ]
}

Type Definitions

GetAssignmentsParams

type GetAssignmentsParams =
  | {
      type?: "assignments"; // Default
      count?: number; // Number of assignments (optional)
    }
  | {
      type: "until";
      date: string; // ISO 8601 date
    }
  | {
      type: "days";
      count: number; // Number of days
    };

ScheduleAssignment

type ScheduleAssignment = {
  userId: string; // User on-call for this assignment
  startDate: string; // ISO 8601 timestamp
  endDate: string; // ISO 8601 timestamp
  assignmentNumber: number; // Position in rotation
};

Common Use Cases

Show Who’s On-Call This Week

const onCall = await client.schedule.getOnCall(schedule.id);
const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "days",
  count: 7,
});

const currentAssignment = assignments.find(
  (a) => a.assignmentNumber === onCall.assignmentNumber
);

if (currentAssignment) {
  console.log(`${onCall.email} is on-call until ${currentAssignment.endDate}`);
}

Display Rotation Calendar

const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "days",
  count: 30,
});

console.log("On-Call Calendar (Next 30 Days):\n");
assignments.forEach((assignment) => {
  const start = new Date(assignment.startDate).toLocaleDateString();
  const end = new Date(assignment.endDate).toLocaleDateString();
  console.log(`${start} - ${end}: ${assignment.userId}`);
});

Find Next Assignment for a User

const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "assignments",
  count: 10,
});

const userId = "usr_alice";
const nextAssignment = assignments.find((a) => a.userId === userId);

if (nextAssignment) {
  console.log(`${userId}'s next on-call starts: ${nextAssignment.startDate}`);
} else {
  console.log(`${userId} not found in next 10 assignments`);
}

Calculate On-Call Load

const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "days",
  count: 90,
});

const userCounts = new Map<string, number>();

assignments.forEach((assignment) => {
  const count = userCounts.get(assignment.userId) || 0;
  userCounts.set(assignment.userId, count + 1);
});

console.log("On-Call Load (Next 90 Days):");
userCounts.forEach((count, userId) => {
  console.log(`${userId}: ${count} assignments`);
});

Vacation Planning

function formatDate(date: Date): string {
  return date.toISOString().split("T")[0];
}

const vacationStart = new Date("2025-03-15");
const vacationEnd = new Date("2025-03-22");

const assignments = await client.schedule.getAssignments(schedule.id, {
  type: "until",
  date: formatDate(vacationEnd),
});

const conflictingAssignments = assignments.filter((assignment) => {
  const start = new Date(assignment.startDate);
  const end = new Date(assignment.endDate);
  return (
    assignment.userId === "usr_alice" &&
    start <= vacationEnd &&
    end >= vacationStart
  );
});

if (conflictingAssignments.length > 0) {
  console.log("⚠️ On-call assignments during vacation:");
  conflictingAssignments.forEach((a) => {
    console.log(`  ${a.startDate} → ${a.endDate}`);
  });
} else {
  console.log("✓ No conflicts with vacation dates");
}

Best Practices

All dates are in UTC—convert to local time zones for display. Cache assignments to reduce API calls since they don’t change frequently.