list_users_oncall
Retrieve users on call for a specific PagerDuty schedule within a defined time range by providing the schedule ID, start time, and end time in ISO8601 format.
Instructions
List the users on call for a schedule during the specified time range.
Args: schedule_id (str): The ID of the schedule to query since (str): Start of query range in ISO8601 format until (str): End of query range in ISO8601 format
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| schedule_id | Yes | ||
| since | No | ||
| until | No |
Implementation Reference
- Core handler function that implements the logic to fetch users on call for a PagerDuty schedule using the API, including validation, API call, parsing, and error handling.
def list_users_oncall( *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None ) -> Dict[str, Any]: """List the users on call for a given schedule during the specified time range. Returns a list of users who are or will be on call during the specified period. Exposed as MCP server tool. Args: schedule_id (str): The ID of the schedule to list users on call for since (str): Start of date range in ISO8601 format (optional). Default is 1 month ago until (str): End of date range in ISO8601 format (optional). Default is now Returns: See the "Standard Response Format" section in `tools.md` for the complete standard response structure. The response will contain a list of users who are on call during the specified time range. Raises: See the "Error Handling" section in `tools.md` for common error scenarios. """ if not schedule_id: raise ValueError("schedule_id cannot be empty") pd_client = create_client() params = {} if since: utils.validate_iso8601_timestamp(since, "since") params["since"] = since if until: utils.validate_iso8601_timestamp(until, "until") params["until"] = until try: response = pd_client.jget(f"{SCHEDULES_URL}/{schedule_id}/users", params=params) try: users_data = response["users"] except KeyError: raise RuntimeError( f"Failed to fetch users on call for schedule {schedule_id}: Response missing 'users' field" ) return utils.api_response_handler( results=[parse_user(result=user) for user in users_data], resource_name="users", ) except Exception as e: utils.handle_api_error(e) - src/pagerduty_mcp_server/server.py:275-288 (registration)MCP tool registration using @mcp.tool() decorator. Defines the tool schema via parameters and docstring, and delegates execution to the core handler in schedules.py.
@mcp.tool() def list_users_oncall( *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None ) -> Dict[str, Any]: """List the users on call for a schedule during the specified time range. Args: schedule_id (str): The ID of the schedule to query since (str): Start of query range in ISO8601 format until (str): End of query range in ISO8601 format """ return schedules.list_users_oncall( schedule_id=schedule_id, since=since, until=until )