Hello Sanchez,
I think there are two separate items here.
1. Empty Schedule Response
The first thing I'd verify is that you're using the correct endpoint. For retrieving published agent schedules:
POST /api/v2/workforcemanagement/businessunits/{businessUnitId}/agentschedules/search
This endpoint can behave a little differently depending on the size of the response.
- For smaller requests, the schedule data is returned directly in the response.
- For larger requests, you'll receive a
downloadUrl that you can use to retrieve the results.
- For very large or long-running requests, the search completes asynchronously and notifies you through the appropriate WFM notification topic.
If you're consistently getting an empty response, I'd also check the permissions of the user making the API call. The caller needs either wfm:schedule:view or wfm:publishedSchedule:view for the appropriate business unit. If permissions are scoped differently (for example, only to specific management units or teams), that can result in empty responses.
If you're handling asynchronous searches, I'd also recommend subscribing to the notification topic before submitting the request so you don't miss the completion event.
2. Predictive Adherence Notifications
I wasn't able to find a native notification that fires before a scheduled activity begins.
The available Workforce Management notification topics are reactive. They'll notify you when:
- A schedule has changed.
- An agent's adherence status changes.
- An agent schedule is modified.
They don't generate an event such as "this agent's break starts in 10 minutes."
If you're looking to build predictive notifications, the approach I'd take is:
- Retrieve agent schedules using the
agentschedules/search endpoint.
- Cache the scheduled activities in your application.
- Calculate upcoming activity start times client-side.
- Subscribe to schedule change notifications so you can refresh your cached schedule whenever it changes.
That gives you a reliable way to generate alerts (for example, 10 minutes before a break or lunch) without continuously polling the API.
You can continue using the adherence notification topics for real-time monitoring once agents actually move in or out of adherence, but those notifications occur after the state change rather than before it.
If you're using notification channels for long-running applications, remember that WebSocket connections expire approximately every 24 hours. I generally recommend renewing the subscription before expiration so you don't miss any events.
Hope this helps!
------------------------------
Cameron
Online Community Manager/Moderator
------------------------------
Original Message:
Sent: 06-29-2026 18:07
From: Jairo Sanchez
Subject: API for Schedule, Required and Performance on Schedule View
Hi Cameron, we have kind of the same situation as Andrew.
We're building a real-time adherence tool on top of Genesys Cloud CX (region: usw2.pure.cloud) and have two related issues:
- Empty schedule response
We're calling the Workforce Management schedules endpoint at the business-unit level for a confirmed valid businessUnitId and weekId (the same week shows published schedules correctly in the WFM UI), but the API call returns an empty result set. We want to confirm: is this endpoint synchronous, or does it require a generate → poll job → downloadUrl flow before the schedule data is available? If there's a known reason schedules return empty despite a valid published week, we'd appreciate pointers - happy to share the exact request/response if useful. - Predictive adherence notifications
Today we monitor agent presence via the Users API (presence/expand) and via the Real-Time Adherence view in the WFM UI, both of which are reactive - they tell us an agent is already in a given state (e.g., already on Lunch, already non-adherent). We need something predictive: an event or notification that fires a configurable number of minutes before a scheduled activity (lunch, break) begins for an agent, so a supervisor can be alerted ahead of a coverage gap rather than after it happens.
Questions:
- Does the Notifications API expose a topic for upcoming scheduled activities (not just state-change/adherence-violation events)?
- If not, is there a recommended pattern for building this predictively (e.g., polling the schedule export and computing "time until next activity" client-side), given that the schedules endpoint above isn't returning data for us yet?
Any guidance - including "this isn't supported, here's the workaround" - is genuinely useful. Thanks.
------------------------------
Santiago Sanchez
Command Alkon
------------------------------
Original Message:
Sent: 06-26-2026 13:57
From: Cameron Tomlin
Subject: API for Schedule, Required and Performance on Schedule View
Hi Andrew,
If you're trying to reproduce the data that's displayed on the Schedule page outside of Genesys Cloud, you'll want to use a couple of Workforce Management APIs together.
The typical flow is:
Retrieve the schedule metadata using:
GET /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekId}/schedules/{scheduleId}
This returns information about the schedule itself, including the management units and agents associated with it.
Retrieve the agent schedule details using:
POST /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekId}/schedules/{scheduleId}/agentschedules/query
This endpoint returns the detailed schedule data for the agents in the schedule and is typically used in conjunction with the metadata endpoint above.
Depending on exactly what you're trying to recreate, there are a few additional endpoints that may be helpful:
- Published agent schedules if you're searching for schedules across one or more agents over a date range.
- Headcount Forecast
GET /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekId}/schedules/{scheduleId}/headcountforecast
This returns the headcount forecast by planning group. - Schedule Generation Results if you're interested in information produced during schedule generation.
In most cases, the first two endpoints are all you'll need. The metadata endpoint identifies the schedule and its contents, while the agentschedules/query endpoint returns the detailed schedule information that's displayed in the Schedule view.
If you're trying to reproduce a specific section of the Schedule page (for example, activities, exceptions, adherence, or staffing data), let me know which portion you're targeting and I can point you to the most appropriate endpoints.
Hope this helps!
------------------------------
Cameron
Online Community Manager/Moderator
------------------------------