List On-Call Schedules

Fetch the on-call schedules in your workspace, with the name and id of whoever is on call right now. Use this to look up a scheduleId before calling On-Call History, or to build a real-time "who is on call" display in your own tooling.

Request

GET https://api.oppex.ai/client/oncall/public/schedules

Send your API key in the X-API-KEY header. All query parameters are optional.

curl -G "https://api.oppex.ai/client/oncall/public/schedules" \
  -H "X-API-KEY: <your-api-key>"

To search by name:

curl -G "https://api.oppex.ai/client/oncall/public/schedules" \
  -H "X-API-KEY: <your-api-key>" \
  --data-urlencode "search=platform" \
  --data-urlencode "pageNumber=1" \
  --data-urlencode "pageSize=20"

Query parameters

Parameter	Description
search	Case-insensitive substring filter on the schedule name. Omit to return all schedules.
pageNumber	Page to return, starting at 1 (the default).
pageSize	Results per page, between 1 and 100. Default is 20.

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Schedules retrieved successfully",
  "data": {
    "items": [
      {
        "scheduleId": 42,
        "scheduleName": "Platform On-Call",
        "timezone": "Asia/Kolkata",
        "active": true,
        "startDate": "2026-01-06",
        "endDate": null,
        "currentOnCall": {
          "userId": 1001,
          "userName": "Alice Chen"
        }
      },
      {
        "scheduleId": 57,
        "scheduleName": "Infra Rotation",
        "timezone": "America/New_York",
        "active": true,
        "startDate": "2026-03-01",
        "endDate": null,
        "currentOnCall": null
      }
    ],
    "totalCount": 12,
    "pageNumber": 1,
    "pageSize": 20
  }
}

Response fields

Field	Description
items[].scheduleId	Numeric id of the schedule. Use this as scheduleId in On-Call History.
items[].scheduleName	Display name of the schedule.
items[].timezone	IANA timezone id the schedule runs in (e.g. Asia/Kolkata, UTC). Rotation changeovers and active-hours windows are evaluated in this zone.
items[].active	true when the schedule is active.
items[].startDate	Date the schedule starts, in the schedule's own timezone.
items[].endDate	Date the schedule ends, or null when it runs indefinitely.
items[].currentOnCall	The person on call right now, or null when nobody is on call (for example, outside a restricted active-hours window). For Notify All schedules, only the first on-call user is shown here — use On-Call History to get the full roster.
totalCount	Total number of schedules matching the query (across all pages).
pageNumber	The page returned.
pageSize	Results per page as requested.

To page through all schedules, repeat the request with pageNumber from 1 up to ceil(totalCount / pageSize).

Errors

Status	When
400	pageNumber or pageSize is out of range. The message says which.
401	The API key is missing, wrong, or disabled. See API Keys.
500	Something went wrong in Oppex. Retry. If it keeps happening, contact support with the message.

FAQ

currentOnCall is null even though the schedule is active — why?

The schedule's active layer may have an active-hours window that doesn't cover right now (for example, a weekday 9 AM–6 PM layer). Outside that window the on-call slot is empty. Use On-Call History with a range that includes the current time to see the full picture including gaps.

I have a Notify All schedule — currentOnCall only shows one person. How do I see everyone?

currentOnCall always reflects only the first on-call user. Call On-Call History for the schedule and check the onCallUsers array on the current span — it contains all members of a Notify All layer.

Can I look up a schedule by service?

Not directly through this API. Search by the schedule name using the search parameter, or look up the schedule id in the Oppex app under Schedules.

The search returned no results but I know the schedule exists.

The search parameter matches on the schedule name only. Check the exact name in the Oppex app, then search for a substring of it.