schedules

Creates, updates, deletes, gets or lists a schedules resource.

Overview

Name	`schedules`
Type	Resource
Id	`pagerduty.schedules_v3.schedules`

Fields

The following fields are returned by SELECT queries:

get
list

Schedule retrieved successfully

Name	Datatype	Description
`id`	`string`	(example: PL5FQHC)
`name`	`string`	(example: Engineering On-Call)
`description`	`string`	(example: Primary engineering on-call rotation)
`escalation_policies`	`array`	Escalation policies that reference this schedule
`final_schedule`	`object`	Computed on-call assignments for the requested time range. Only present when `include[]=final_schedule` is specified and `since`/`until` are provided.
`html_url`	`string (uri)`
`http_cal_url`	`string (uri)`	iCal HTTP feed URL for this schedule
`rotations`	`array`	Rotations in this schedule
`self`	`string (uri)`
`teams`	`array`
`time_zone`	`string`	(example: America/New_York)
`type`	`string`	Always `"schedule_v3"` for schedules created with this API. Schedules created with the legacy `/schedules` API use `"schedule"`. (schedule_v3)
`users`	`array`	All users referenced in this schedule (only present when include[]=users)
`web_cal_url`	`string (uri)`	iCal webcal URL for this schedule

Schedules retrieved successfully

Name	Datatype	Description
`id`	`string`	(example: PL5FQHC)
`html_url`	`string (uri)`	(example: https://example.pagerduty.com/schedules/PL5FQHC)
`self`	`string (uri)`	(example: https://api.pagerduty.com/v3/schedules/PL5FQHC)
`summary`	`string`	Schedule name (example: Engineering On-Call)
`type`	`string`	(schedule_v3_reference)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`id`	`since`, `until`, `time_zone`, `overflow`, `include[]`	<!-- theme: info --><br /><br />> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to:<br />><br />> 1. Update your automations to use the V3 API for all new shift-based schedules<br />> 2. Keep the V2 endpoint for your existing schedules<br />><br />> An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples).<br /><br />Retrieve a schedule by ID including rotations and events. Optionally<br />include the computed final schedule for a time range.<br /><br />Use `include[]=final_schedule` to get computed on-call assignments.<br />Use `since` and `until` to specify the time range.<br />
`list`	`select`		`limit`, `offset`, `query`, `total`, `team_ids[]`	<!-- theme: info --><br /><br />> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to:<br />><br />> 1. Update your automations to use the V3 API for all new shift-based schedules<br />> 2. Keep the V2 endpoint for your existing schedules<br />><br />> An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples).<br /><br />Retrieve a paginated list of schedule references. Returns lightweight<br />objects without embedded rotations or events.<br /><br />Each result is filtered by the caller's read permission; schedules the<br />caller cannot read are silently excluded.<br />
`create`	`insert`	`schedule`		<!-- theme: info --><br /><br />> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to:<br />><br />> 1. Update your automations to use the V3 API for all new shift-based schedules<br />> 2. Keep the V2 endpoint for your existing schedules<br />><br />> An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples).<br /><br />Create a new on-call schedule with basic metadata. Rotations and events<br />must be added via separate API calls after creation.<br /><br />Rejected fields: `rotations` and `escalation_policies` are not<br />accepted in the request body and will result in a 400 error.<br />
`update`	`update`	`id`, `schedule`		<!-- theme: info --><br /><br />> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to:<br />><br />> 1. Update your automations to use the V3 API for all new shift-based schedules<br />> 2. Keep the V2 endpoint for your existing schedules<br />><br />> An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples).<br /><br />Update schedule metadata (name, description, time zone). All fields are<br />optional — only provided fields are updated.<br /><br />To modify rotations or events, use their respective endpoints.<br /><br />Rejected fields: `rotations` and `escalation_policies` are not<br />accepted and will result in a 400 error.<br />
`delete`	`delete`	`id`		<!-- theme: info --><br /><br />> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to:<br />><br />> 1. Update your automations to use the V3 API for all new shift-based schedules<br />> 2. Keep the V2 endpoint for your existing schedules<br />><br />> An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples).<br /><br />Delete a schedule and all associated rotations and events.<br /><br />If the schedule is referenced by an active escalation policy, the<br />deletion will be rejected.<br />

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`id`	`string`	The ID of the schedule. (example: PSJUKNI)
`include[]`	`array`	Additional data to include in the schedule response: - `final_schedule`: computed on-call assignments for the time range (example: [final_schedule])
`limit`	`integer`	Maximum number of schedules to return
`offset`	`integer`
`overflow`	`boolean`	Include shifts that extend beyond the requested time range boundaries
`query`	`string`	Filters the result, showing only the records whose name matches the query.
`since`	`string (date-time)`	Start of time range (ISO 8601) (example: 2025-01-01T00:00:00Z)
`team_ids[]`	`array`	An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.
`time_zone`	`string`	IANA timezone identifier for rendering shift times. Defaults to the schedule's configured time zone. (example: America/New_York)
`total`	`boolean`	By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated. See our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.
`until`	`string (date-time)`	End of time range (ISO 8601) (example: 2025-01-31T23:59:59Z)

`SELECT` examples

get
list

> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to: > > 1. Update your automations to use the V3 API for all new shift-based schedules > 2. Keep the V2 endpoint for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a schedule by ID including rotations and events. Optionally include the computed final schedule for a time range. Use include[]=final_schedule to get computed on-call assignments. Use since and until to specify the time range.

SELECT
id,
name,
description,
escalation_policies,
final_schedule,
html_url,
http_cal_url,
rotations,
self,
teams,
time_zone,
type,
users,
web_cal_url
FROM pagerduty.schedules_v3.schedules
WHERE id = '{{ id }}' -- required
AND since = '{{ since }}'
AND until = '{{ until }}'
AND time_zone = '{{ time_zone }}'
AND overflow = '{{ overflow }}'
AND include[] = '{{ include[] }}'
;

> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to: > > 1. Update your automations to use the V3 API for all new shift-based schedules > 2. Keep the V2 endpoint for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a paginated list of schedule references. Returns lightweight objects without embedded rotations or events. Each result is filtered by the caller's read permission; schedules the caller cannot read are silently excluded.

SELECT
id,
html_url,
self,
summary,
type
FROM pagerduty.schedules_v3.schedules
WHERE limit = '{{ limit }}'
AND offset = '{{ offset }}'
AND query = '{{ query }}'
AND total = '{{ total }}'
AND team_ids[] = '{{ team_ids[] }}'
;

`INSERT` examples

create
Manifest

> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to: > > 1. Update your automations to use the V3 API for all new shift-based schedules > 2. Keep the V2 endpoint for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Create a new on-call schedule with basic metadata. Rotations and events must be added via separate API calls after creation. Rejected fields: rotations and escalation_policies are not accepted in the request body and will result in a 400 error.

INSERT INTO pagerduty.schedules_v3.schedules (
schedule
)
SELECT 
'{{ schedule }}' /* required */
RETURNING
schedule
;

# Description fields are for documentation purposes
- name: schedules
props:
  - name: schedule
    value:
      name: "{{ name }}"
      time_zone: "{{ time_zone }}"
      description: "{{ description }}"
      teams:
        - id: "{{ id }}"
          type: "{{ type }}"

`UPDATE` examples

update

> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to: > > 1. Update your automations to use the V3 API for all new shift-based schedules > 2. Keep the V2 endpoint for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Update schedule metadata (name, description, time zone). All fields are optional — only provided fields are updated. To modify rotations or events, use their respective endpoints. Rejected fields: rotations and escalation_policies are not accepted and will result in a 400 error.

UPDATE pagerduty.schedules_v3.schedules
SET 
schedule = '{{ schedule }}'
WHERE 
id = '{{ id }}' --required
AND schedule = '{{ schedule }}' --required
RETURNING
schedule;

`DELETE` examples

delete

> Important note: Shift-based schedules use the V3 API and are not compatible with V2 automations. To create automations for Shift-Based Schedules, you need to: > > 1. Update your automations to use the V3 API for all new shift-based schedules > 2. Keep the V2 endpoint for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Delete a schedule and all associated rotations and events. If the schedule is referenced by an active escalation policy, the deletion will be rejected.

DELETE FROM pagerduty.schedules_v3.schedules
WHERE id = '{{ id }}' --required
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​