get_schedules
Fetch PagerDuty schedules by IDs, filters, or search queries. Retrieve schedule details, overrides, and time-bound data for effective team and incident management.
Instructions
Get PagerDuty schedules by filters or get details for a specific schedule ID.
Args:
schedule_id (str): The schedule ID to retrieve details for (optional, cannot be used with query or limit).
query (str): Filter schedules whose names contain the search query (optional). Not used if schedule_id is provided.
limit (int): Limit the number of results returned (optional). Not used if schedule_id is provided.
since (str): Start time for overrides/final schedule details (ISO8601, optional). Only used if schedule_id is provided. Defaults to 2 weeks before 'until' if 'until' is given.
until (str): End time for overrides/final schedule details (ISO8601, optional). Only used if schedule_id is provided. Defaults to 2 weeks after 'since' if 'since' is given.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| schedule_id | No | ||
| since | No | ||
| until | No |
Implementation Reference
- Handler function for the 'get_schedules' tool. Dispatches to list_schedules or show_schedule helpers based on whether a specific schedule_id is provided. Includes input validation and documentation.@mcp.tool() def get_schedules( *, schedule_id: Optional[str] = None, query: Optional[str] = None, limit: Optional[int] = None, since: Optional[str] = None, until: Optional[str] = None, ) -> Dict[str, Any]: """Get PagerDuty schedules by filters or get details for a specific schedule ID. Args: schedule_id (str): The schedule ID to retrieve details for (optional, cannot be used with query or limit). query (str): Filter schedules whose names contain the search query (optional). Not used if `schedule_id` is provided. limit (int): Limit the number of results returned (optional). Not used if `schedule_id` is provided. since (str): Start time for overrides/final schedule details (ISO8601, optional). Only used if `schedule_id` is provided. Defaults to 2 weeks before 'until' if 'until' is given. until (str): End time for overrides/final schedule details (ISO8601, optional). Only used if `schedule_id` is provided. Defaults to 2 weeks after 'since' if 'since' is given. """ if schedule_id is not None: if query is not None or limit is not None: raise ValueError( "When `schedule_id` is provided, other filters (query, limit) cannot be used. See `docs://tools` for more information." ) return schedules.show_schedule( schedule_id=schedule_id, since=since, until=until ) else: return schedules.list_schedules(query=query, limit=limit)
- Helper function called by get_schedules to list schedules matching the query and limit parameters using the PagerDuty API.def list_schedules( *, query: Optional[str] = None, limit: Optional[int] = None ) -> Dict[str, Any]: """List existing PagerDuty schedules. Returns all schedules that match the given search criteria. Exposed in `get_schedules`. Args: query (str): Filter schedules whose names contain the search query (optional) limit (int): Limit the number of results returned (optional) Returns: See the "Standard Response Format" section in `tools.md` for the complete standard response structure. The response will contain a list of schedules with their configuration and team assignments. Raises: See the "Error Handling" section in `tools.md` for common error scenarios. """ pd_client = create_client() params = {} if query: params["query"] = query if limit: params["limit"] = limit try: response = pd_client.list_all(SCHEDULES_URL, params=params) parsed_response = [parse_schedule(result=result) for result in response] return utils.api_response_handler( results=parsed_response, resource_name="schedules" ) except Exception as e: utils.handle_api_error(e)
- Helper function called by get_schedules to retrieve detailed information for a specific schedule, including overrides over a time range, using the PagerDuty API.def show_schedule( *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None ) -> Dict[str, Any]: """Get detailed information about a given schedule, including its configuration and current state. Exposed in `get_schedules`. Args: schedule_id (str): The ID of the schedule to get 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 single schedule with detailed configuration and team information. 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}", params=params) try: schedule_data = response["schedule"] except KeyError: raise RuntimeError( f"Failed to fetch schedule {schedule_id}: Response missing 'schedule' field" ) return utils.api_response_handler( results=parse_schedule(result=schedule_data), resource_name="schedule" ) except Exception as e: utils.handle_api_error(e)