Who Is On Call
Returns who is on call right now in your organization, one entry per team, escalation tier and person, resolved exactly like the paging engine.
GET /api/im/on-call
Returns who is on call right now in your organization: one entry per team, escalation tier and person. It uses exactly the same resolution as GET /api/im/teams/{id}/on-call-now and the paging engine: the schedule's rotation computed at request time (not only the materialized shifts), every schedule override (all tiers and tier-scoped), every team-level override and every concurrent peer. An override you create, edit or delete counts immediately; there is no wait for the shifts to be re-materialized.
Authentication
Requires the base IM access every endpoint in this API needs (an IM-eligible admin, editor, or responder role, or an organization-wide API token; Incident Management must be enabled for the organization).
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
envelope | string | none | items: answer as { items, total, page, perPage }. Becomes the default on 2027-01-18. |
Example (cURL)
curl -X GET "$BASE_URL/api/im/on-call?envelope=items" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"Response
200 OK: one entry per team, tier and person currently on call. A tier with no one covering right now (a gap) is simply absent from the list. It is not returned as null or an error. A team without any schedule at all (only team-level overrides) does not appear in this list either, because scheduleId cannot be filled; its on-call people are visible via GET /api/im/teams/{id}/on-call-now.
{
"items": [
{
"teamId": 3,
"tierId": 12,
"tierOrder": 1,
"scheduleId": 7,
"sourceScheduleId": 7,
"userId": "MFcTjWmYq2LpzR8vK1sXo",
"userName": "Grace Hopper",
"userImage": "/api/assets/avatar/MFcTjWmYq2LpzR8vK1sXo",
"shiftEndsAt": "2026-07-18T09:00:00.000Z",
"shiftEndsAtIsLowerBound": false
}
],
"total": 1,
"page": 1,
"perPage": 1
}List form: with envelope=items the list arrives as { items, total, page, perPage }. Without it the endpoint still answers the current form (a bare array of the same entries), which is deprecated; { items, ... } becomes the default on 2027-01-18.
userImage is the avatar delivery URL, or null when the person has no picture. A self-uploaded picture sits behind an authorizing path on this API and must be requested with the same credentials.
| Field | Description |
|---|---|
teamId | The team. |
tierId | The escalation tier the person is on call for. |
tierOrder | Position of that tier in the team's escalation chain, 1-based. |
scheduleId | Legacy field, always set: the schedule the person comes from, else the tier's first schedule, else the team's first schedule. Use sourceScheduleId for the exact value. |
sourceScheduleId | The schedule whose rotation and overrides put the person on call, or null when only a team-level override does. |
userId, userName, userImage | The person on call. |
shiftEndsAt | End of the person's uninterrupted duty in this tier: the next moment they are no longer on call. Rotation periods in which the same person is on again right after, back-to-back shifts and overrides are crossed, so a one-person schedule running until 31 December reports 31 December, not the end of the current rotation period. An override that takes the duty away ends it at the override's start. |
shiftEndsAtIsLowerBound | true when the duty does not end within the next 90 days (the look-ahead). shiftEndsAt is then only "on call at least until", not an end. false for every real end. |
The list agrees with GET /api/im/teams/{id}/on-call-now and with the set the escalation engine starts from. shiftEndsAt is computed in one place for all three on-call endpoints: the same person in the same tier has the same shiftEndsAt here and in on-call-now, and currentShift.endsAt of GET /api/im/me/on-call is that value too (null there where shiftEndsAtIsLowerBound is true here). A round-robin tier has no single "now": round robin narrows the set per incident at the moment it pages, so this list shows the full, un-narrowed set (the same as the team strip in the dashboard).
Common errors
401 Unauthorizedwhen not authenticated403 Forbidden(customerScopedTokenForbidden) when using a customer-scoped token403 Forbidden(imAccessDenied) when the session user has no IM-eligible role403 Forbidden(imNotEnabled) when Incident Management is not enabled for the organization