incidents

Creates, updates, deletes, gets or lists an incidents resource.

Overview

Name	incidents
Type	Resource
Id	pagerduty.incidents.incidents

Fields

The following fields are returned by SELECT queries:

get_incident

The incident requested.

Name	Datatype	Description
id	string
acknowledgements	array	List of all acknowledgements for this incident. This list will be empty if the Incident.status is resolved or triggered.
alert_counts	object
assigned_via	string	How the current incident assignments were decided. Note that direct_assignment incidents will not escalate up the attached escalation_policy
assignments	array	List of all assignments for this incident. This list will be empty if the Incident.status is resolved.
body	object
conference_bridge	object
created_at	string (date-time)	The date/time the incident was first triggered.
escalation_policy	object
first_trigger_log_entry	object
html_url	string (url)	a URL at which the entity is uniquely displayed in the Web app
incident_key	string	The incident's de-duplication key.
incident_number	integer	The number of the incident. This is unique across your account.
incidents_responders	array
last_status_change_at	string (date-time)	The time at which the status of the incident last changed.
last_status_change_by	object	The agent (user, service or integration) that created or modified the Incident Log Entry.
pending_actions	array	The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to.
priority	object
resolve_reason	object
responder_requests	array
self	string (url)	the API show URL at which the object is accessible
service	object
status	string	The current status of the incident.
summary	string	A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to name, though it is not intended to be an identifier.
teams	array	The teams involved in the incident’s lifecycle.
title	string	A succinct description of the nature, symptoms, cause, or effect of the incident.
type	string	A string that determines the schema of the object. This must be the standard name for the entity, suffixed by _reference if the object is a reference.
urgency	string	The current urgency of the incident.

list_incidents

A paginated array of incidents.

Name	Datatype	Description
id	string
acknowledgements	array	List of all acknowledgements for this incident. This list will be empty if the Incident.status is resolved or triggered.
alert_counts	object
assigned_via	string	How the current incident assignments were decided. Note that direct_assignment incidents will not escalate up the attached escalation_policy
assignments	array	List of all assignments for this incident. This list will be empty if the Incident.status is resolved.
body	object
conference_bridge	object
created_at	string (date-time)	The date/time the incident was first triggered.
escalation_policy	object
first_trigger_log_entry	object
html_url	string (url)	a URL at which the entity is uniquely displayed in the Web app
incident_key	string	The incident's de-duplication key.
incident_number	integer	The number of the incident. This is unique across your account.
incidents_responders	array
last_status_change_at	string (date-time)	The time at which the status of the incident last changed.
last_status_change_by	object	The agent (user, service or integration) that created or modified the Incident Log Entry.
pending_actions	array	The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to.
priority	object
resolve_reason	object
responder_requests	array
self	string (url)	the API show URL at which the object is accessible
service	object
status	string	The current status of the incident.
summary	string	A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to name, though it is not intended to be an identifier.
teams	array	The teams involved in the incident’s lifecycle.
title	string	A succinct description of the nature, symptoms, cause, or effect of the incident.
type	string	A string that determines the schema of the object. This must be the standard name for the entity, suffixed by _reference if the object is a reference.
urgency	string	The current urgency of the incident.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_incident	select	id, X-EARLY-ACCESS	Accept, Content-Type, include[]	Show detailed information about an incident. Accepts either an incident id, or an incident number. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document <!-- theme: warning --> > ### Early Access > The include[]=field_values part of this endpoint is in Early Access and may change at any time. You must pass in the X-EARLY-ACCESS header to access it. Scoped OAuth requires: incidents.read
list_incidents	select		Accept, Content-Type, limit, offset, total, date_range, incident_key, service_ids[], team_ids[], user_ids[], urgencies[], time_zone, statuses[], sort_by, include[], since, until	List existing incidents. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.read
create_incident	insert	From, data__incident	Accept, Content-Type	Create an incident synchronously without a corresponding event from a monitoring service. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
_list_incidents	exec		Accept, Content-Type, limit, offset, total, date_range, incident_key, service_ids[], team_ids[], user_ids[], urgencies[], time_zone, statuses[], sort_by, include[], since, until	List existing incidents. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.read
update_incidents	exec	From, incidents	Accept, Content-Type, limit, offset, total	Acknowledge, resolve, escalate or reassign one or more incidents. An incident represents a problem or an issue that needs to be addressed and resolved. A maximum of 250 incidents may be updated at a time. If more than this number of incidents are given, the API will respond with status 413 (Request Entity Too Large). Note: the manage incidents API endpoint is rate limited to 500 requests per minute. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
_get_incident	exec	id, X-EARLY-ACCESS	Accept, Content-Type, include[]	Show detailed information about an incident. Accepts either an incident id, or an incident number. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document <!-- theme: warning --> > ### Early Access > The include[]=field_values part of this endpoint is in Early Access and may change at any time. You must pass in the X-EARLY-ACCESS header to access it. Scoped OAuth requires: incidents.read
update_incident	exec	id, From, incident	Accept, Content-Type	Acknowledge, resolve, escalate or reassign an incident. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
merge_incidents	exec	id, From, source_incidents	Accept, Content-Type	Merge a list of source incidents into this incident. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
create_incident_responder_request	exec	id, From, requester_id, message, responder_request_targets	Accept, Content-Type	Send a new responder request for the specified incident. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
create_incident_snooze	exec	id, From, duration	Accept, Content-Type	Snooze an incident. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
create_incident_status_update	exec	id, From, message	Accept, Content-Type	Create a new status update for the specified incident. Optionally pass subject and html_message properties in the request body to override the email notification that gets sent. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the API Concepts Document Scoped OAuth requires: incidents.write
remove_incident_notification_subscribers	exec	id, subscribers	Accept	Unsubscribes the matching Subscribers from Incident Status Update Notifications. Scoped OAuth requires: subscribers.write

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
From	string (email)	The email address of a valid user associated with the account making the request.
X-EARLY-ACCESS	string	This header indicates that this API endpoint is UNDER CONSTRUCTION and may change at any time. You MUST pass in this header and the above value. Do not use this endpoint in production, as it may change!
id	string	The ID of the resource.
Accept	string	The Accept header is used as a versioning header.
Content-Type	string
date_range	string	When set to all, the since and until parameters and defaults are ignored.
incident_key	string	Incident de-duplication key. Incidents with child alerts do not have an incident key; querying by incident key will return incidents whose alerts have alert_key matching the given incident key.
include[]	string	Array of additional details to include.
limit	integer	The number of results per page.
offset	integer	Offset to start pagination search results.
service_ids[]	array	Returns only the incidents associated with the passed service(s). This expects one or more service IDs.
since	string	The start of the date range over which you want to search. Maximum range is 6 months and default is 1 month.
sort_by	array	Used to specify both the field you wish to sort the results on (incident_number/created_at/resolved_at/urgency), as well as the direction (asc/desc) of the results. The sort_by field and direction should be separated by a colon. A maximum of two fields can be included, separated by a comma. Sort direction defaults to ascending. The account must have the urgencies ability to sort by the urgency.
statuses[]	string	Return only incidents with the given statuses. To query multiple statuses, pass statuses[] more than once, for example: https://api.pagerduty.com/incidents?statuses[]=triggered&statuses[]=acknowledged. (More status codes may be introduced in the future.)
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 (tzinfo)	Time zone in which dates in the result will be rendered.
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 for more information.
until	string	The end of the date range over which you want to search. Maximum range is 6 months and default is 1 month.
urgencies[]	string	Array of the urgencies of the incidents to be returned. Defaults to all urgencies. Account must have the urgencies ability to do this.
user_ids[]	array	Returns only the incidents currently assigned to the passed user(s). This expects one or more user IDs. Note: When using the assigned_to_user filter, you will only receive incidents with statuses of triggered or acknowledged. This is because resolved incidents are not assigned to any user.

SELECT examples

get_incident

Show detailed information about an incident. Accepts either an incident id, or an incident number.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

<!-- theme: warning -->
> ### Early Access
> The include[]=field_values part of this endpoint is in Early Access and may change at any time. You must pass in the X-EARLY-ACCESS header to access it.

Scoped OAuth requires: incidents.read

SELECT
id,
acknowledgements,
alert_counts,
assigned_via,
assignments,
body,
conference_bridge,
created_at,
escalation_policy,
first_trigger_log_entry,
html_url,
incident_key,
incident_number,
incidents_responders,
last_status_change_at,
last_status_change_by,
pending_actions,
priority,
resolve_reason,
responder_requests,
self,
service,
status,
summary,
teams,
title,
type,
urgency
FROM pagerduty.incidents.incidents
WHERE id = '{{ id }}' -- required
AND X-EARLY-ACCESS = '{{ X-EARLY-ACCESS }}' -- required
AND Accept = '{{ Accept }}'
AND Content-Type = '{{ Content-Type }}'
AND include[] = '{{ include[] }}'
;

list_incidents

List existing incidents.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.read

SELECT
id,
acknowledgements,
alert_counts,
assigned_via,
assignments,
body,
conference_bridge,
created_at,
escalation_policy,
first_trigger_log_entry,
html_url,
incident_key,
incident_number,
incidents_responders,
last_status_change_at,
last_status_change_by,
pending_actions,
priority,
resolve_reason,
responder_requests,
self,
service,
status,
summary,
teams,
title,
type,
urgency
FROM pagerduty.incidents.incidents
WHERE Accept = '{{ Accept }}'
AND Content-Type = '{{ Content-Type }}'
AND limit = '{{ limit }}'
AND offset = '{{ offset }}'
AND total = '{{ total }}'
AND date_range = '{{ date_range }}'
AND incident_key = '{{ incident_key }}'
AND service_ids[] = '{{ service_ids[] }}'
AND team_ids[] = '{{ team_ids[] }}'
AND user_ids[] = '{{ user_ids[] }}'
AND urgencies[] = '{{ urgencies[] }}'
AND time_zone = '{{ time_zone }}'
AND statuses[] = '{{ statuses[] }}'
AND sort_by = '{{ sort_by }}'
AND include[] = '{{ include[] }}'
AND since = '{{ since }}'
AND until = '{{ until }}'
;

INSERT examples

create_incident

Create an incident synchronously without a corresponding event from a monitoring service.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

INSERT INTO pagerduty.incidents.incidents (
data__incident,
From,
Accept,
Content-Type
)
SELECT 
'{{ incident }}' /* required */,
'{{ From }}',
'{{ Accept }}',
'{{ Content-Type }}'
RETURNING
incident
;

Manifest

# Description fields are for documentation purposes
- name: incidents
  props:
    - name: From
      value: string (email)
      description: Required parameter for the incidents resource.
    - name: incident
      value: object
      description: |
        Details of the incident to be created.
    - name: Accept
      value: string
      description: The `Accept` header is used as a versioning header.
    - name: Content-Type
      value: string

Lifecycle Methods

_list_incidents

List existing incidents.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.read

EXEC pagerduty.incidents.incidents._list_incidents 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}', 
@limit='{{ limit }}', 
@offset='{{ offset }}', 
@total={{ total }}, 
@date_range='{{ date_range }}', 
@incident_key='{{ incident_key }}', 
@service_ids[]='{{ service_ids[] }}', 
@team_ids[]='{{ team_ids[] }}', 
@user_ids[]='{{ user_ids[] }}', 
@urgencies[]='{{ urgencies[] }}', 
@time_zone='{{ time_zone }}', 
@statuses[]='{{ statuses[] }}', 
@sort_by='{{ sort_by }}', 
@include[]='{{ include[] }}', 
@since='{{ since }}', 
@until='{{ until }}'
;

update_incidents

Acknowledge, resolve, escalate or reassign one or more incidents.

An incident represents a problem or an issue that needs to be addressed and resolved.

A maximum of 250 incidents may be updated at a time. If more than this number of incidents are given, the API will respond with status 413 (Request Entity Too Large).

Note: the manage incidents API endpoint is rate limited to 500 requests per minute.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.update_incidents 
@From='{{ From }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}', 
@limit='{{ limit }}', 
@offset='{{ offset }}', 
@total={{ total }} 
@@json=
'{
"incidents": "{{ incidents }}"
}'
;

_get_incident

Show detailed information about an incident. Accepts either an incident id, or an incident number.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

<!-- theme: warning -->
> ### Early Access
> The include[]=field_values part of this endpoint is in Early Access and may change at any time. You must pass in the X-EARLY-ACCESS header to access it.

Scoped OAuth requires: incidents.read

EXEC pagerduty.incidents.incidents._get_incident 
@id='{{ id }}' --required, 
@X-EARLY-ACCESS='{{ X-EARLY-ACCESS }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}', 
@include[]='{{ include[] }}'
;

update_incident

Acknowledge, resolve, escalate or reassign an incident.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.update_incident 
@id='{{ id }}' --required, 
@From='{{ From }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}' 
@@json=
'{
"incident": "{{ incident }}"
}'
;

merge_incidents

Merge a list of source incidents into this incident.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.merge_incidents 
@id='{{ id }}' --required, 
@From='{{ From }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}' 
@@json=
'{
"source_incidents": "{{ source_incidents }}"
}'
;

create_incident_responder_request

Send a new responder request for the specified incident.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.create_incident_responder_request 
@id='{{ id }}' --required, 
@From='{{ From }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}' 
@@json=
'{
"requester_id": "{{ requester_id }}", 
"message": "{{ message }}", 
"responder_request_targets": "{{ responder_request_targets }}"
}'
;

create_incident_snooze

Snooze an incident.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.create_incident_snooze 
@id='{{ id }}' --required, 
@From='{{ From }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}' 
@@json=
'{
"duration": {{ duration }}
}'
;

create_incident_status_update

Create a new status update for the specified incident. Optionally pass subject and html_message properties in the request body to override the email notification that gets sent.

An incident represents a problem or an issue that needs to be addressed and resolved.

For more information see the API Concepts Document

Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.create_incident_status_update 
@id='{{ id }}' --required, 
@From='{{ From }}' --required, 
@Accept='{{ Accept }}', 
@Content-Type='{{ Content-Type }}' 
@@json=
'{
"message": "{{ message }}", 
"subject": "{{ subject }}", 
"html_message": "{{ html_message }}"
}'
;

remove_incident_notification_subscribers

Unsubscribes the matching Subscribers from Incident Status Update Notifications.

Scoped OAuth requires: subscribers.write

EXEC pagerduty.incidents.incidents.remove_incident_notification_subscribers 
@id='{{ id }}' --required, 
@Accept='{{ Accept }}' 
@@json=
'{
"subscribers": "{{ subscribers }}"
}'
;