Overview
Retrieves on-call assignments across schedules, showing who is on-call now or during a specific time period. Supports filtering by schedule, user, escalation policy, and time range.This is a read-only tool that does not modify any data in your PagerDuty account.
Parameters
All parameters are optional and can be combined to filter results:Filter on-call assignments by schedule IDs. Returns only assignments from the specified schedules.
Filter by user IDs. Returns only assignments for the specified users.
Filter by escalation policy IDs. Returns assignments associated with specific escalation policies.
Start of the time range to query. Defaults to the current time. Use ISO 8601 format.
End of the time range to query. Defaults to the current time. Use ISO 8601 format.
Time zone for rendering dates (IANA format, e.g., “America/New_York”). If not specified, uses the schedule’s time zone.
If true, returns only the earliest on-call for each combination of user and escalation policy. Set to false to see all on-call assignments including overlapping coverage.
Maximum number of on-call assignments to return. Must be between 1 and 100.
Response
Returns a list of on-call assignments. Each assignment includes:The user who is on-call:
id- User IDsummary- User namehtml_url- Link to user profile
The schedule for this assignment:
id- Schedule IDsummary- Schedule namehtml_url- Link to schedule
The escalation policy associated with this on-call:
id- Escalation policy IDsummary- Policy namehtml_url- Link to policy
The level in the escalation policy (1 for first level, 2 for second level, etc.)
When this on-call shift starts. Null for permanent on-call assignments.
When this on-call shift ends. Null if the user remains on-call indefinitely.
Example Usage
Check who is currently on-call
Find on-call for specific schedule
Check future on-call assignments
View a user’s upcoming on-call shifts
Check all on-call during a time period
View on-call for multiple schedules
Understanding On-Call Assignments
Escalation Levels
On-call assignments are tied to escalation policies with multiple levels:- Level 1 - The first responder for incidents
- Level 2 - The second responder if level 1 doesn’t respond
- Level 3+ - Additional escalation levels
Time Ranges
By default, the tool returns current on-call assignments. Usesince and until to query:
- Past assignments - See historical on-call data
- Future assignments - Plan ahead and verify rotations
- Specific time windows - Check coverage during maintenance windows or holidays
Overlapping Coverage
Ifearliest=true (default), you see one assignment per user/policy combination. Set earliest=false to see all assignments, including:
- Multiple layers in the same schedule
- Overlapping overrides
- Backup coverage
Common Use Cases
- Incident response - Quickly identify who to contact for an incident
- Coverage verification - Ensure all schedules have on-call coverage
- Planning - Review upcoming on-call assignments for time off requests
- Audit - Track historical on-call data for load balancing
- Status checks - Display current on-call status in dashboards or reports
- Team coordination - Identify which team members are on-call when scheduling meetings
Important Notes
This tool respects schedule overrides. If a schedule has an active override, the override user will be shown as on-call instead of the regularly scheduled user.
Related Tools
get_schedule
View schedule configuration
list_schedules
List all schedules
create_override
Create temporary on-call overrides
get_escalation_policy
View escalation policy details
See Also
- On-Call Management Guide - Best practices for managing on-call