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
list

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`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry.
`alert_counts`	`object`
`alert_grouping`	`object`	Describes the alert grouping state of this incident. Will be null if the incident has no alerts.
`assigned_via`	`string`	How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` (escalation_policy, direct_assignment)
`assignments`	`array`	List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided.
`body`	`object`	The additional incident body details. Only returned if the `include[]=body` query parameter is provided.
`conference_bridge`	`object`	The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided.
`created_at`	`string (date-time)`	The time the incident was first triggered. (example: 2019-12-01T20:00:00Z)
`escalation_policy`		The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned.
`first_trigger_log_entry`		The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned.
`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.
`incident_type`	`object`	The incident type of the incident.
`incidents_responders`	`array`	The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature.
`is_mergeable`	`boolean`	Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged.
`last_status_change_at`	`string (date-time)`	The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. (example: 2019-12-01T21:01:00Z)
`last_status_change_by`		The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned.
`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`
`resolved_at`	`string (date-time)`	The time the incident became "resolved" or `null` if the incident is not resolved. (example: 2019-12-01T21:01:00Z)
`responder_requests`	`array`	Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature.
`self`	`string (url)`	the API show URL at which the object is accessible
`service`		The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned.
`status`	`string`	The current status of the incident. (triggered, acknowledged, resolved)
`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. If the `include[]=teams` query parameter is provided, the full team definitions will be returned.
`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.
`updated_at`	`string (date-time)`	The time the incident was last modified. (example: 2019-12-01T21:02:00Z)
`urgency`	`string`	The current urgency of the incident. (high, low)

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`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry.
`alert_counts`	`object`
`alert_grouping`	`object`	Describes the alert grouping state of this incident. Will be null if the incident has no alerts.
`assigned_via`	`string`	How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` (escalation_policy, direct_assignment)
`assignments`	`array`	List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided.
`body`	`object`	The additional incident body details. Only returned if the `include[]=body` query parameter is provided.
`conference_bridge`	`object`	The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided.
`created_at`	`string (date-time)`	The time the incident was first triggered. (example: 2019-12-01T20:00:00Z)
`escalation_policy`		The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned.
`first_trigger_log_entry`		The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned.
`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.
`incident_type`	`object`	The incident type of the incident.
`incidents_responders`	`array`	The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature.
`is_mergeable`	`boolean`	Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged.
`last_status_change_at`	`string (date-time)`	The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. (example: 2019-12-01T21:01:00Z)
`last_status_change_by`		The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned.
`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`
`resolved_at`	`string (date-time)`	The time the incident became "resolved" or `null` if the incident is not resolved. (example: 2019-12-01T21:01:00Z)
`responder_requests`	`array`	Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature.
`self`	`string (url)`	the API show URL at which the object is accessible
`service`		The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned.
`status`	`string`	The current status of the incident. (triggered, acknowledged, resolved)
`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. If the `include[]=teams` query parameter is provided, the full team definitions will be returned.
`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.
`updated_at`	`string (date-time)`	The time the incident was last modified. (example: 2019-12-01T21:02:00Z)
`urgency`	`string`	The current urgency of the incident. (high, low)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`id`	`include[]`	Show detailed information about an incident. Accepts either an incident id, or an incident number.<br /><br />An incident represents a problem or an issue that needs to be addressed and resolved.<br /><br />For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents)<br /><br />Scoped OAuth requires: `incidents.read`<br />
`list`	`select`		`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.<br /><br />An incident represents a problem or an issue that needs to be addressed and resolved.<br /><br />For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents)<br /><br />Scoped OAuth requires: `incidents.read`<br />
`create`	`insert`	`incident`	`From`	Create an incident synchronously without a corresponding event from a monitoring service.<br /><br />An incident represents a problem or an issue that needs to be addressed and resolved.<br /><br />For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents)<br /><br />Scoped OAuth requires: `incidents.write`<br /><br />This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.<br />
`update`	`update`	`id`, `incident`	`From`	Acknowledge, resolve, escalate or reassign an incident.<br /><br />An incident represents a problem or an issue that needs to be addressed and resolved.<br /><br />For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents)<br /><br />Scoped OAuth requires: `incidents.write`<br />
`update_bulk`	`exec`	`incidents`	`limit`, `offset`, `total`, `From`	Acknowledge, resolve, escalate or reassign one or more incidents.<br /><br />An incident represents a problem or an issue that needs to be addressed and resolved.<br /><br />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).<br /><br />For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents)<br /><br />Scoped OAuth requires: `incidents.write`<br /><br />This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.<br />
`merge`	`exec`	`id`, `source_incidents`	`From`	Merge a list of source incidents into the target [incident](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents).<br /><br />After the merge is performed the target incident will contain the source incidents' [alerts](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#alerts),<br />and the source incidents will be resolved.<br /><br />Only incidents that have alerts or incidents that were created manually in the UI can be merged.<br /><br />Open incidents cannot be merged into a resolved incident. The target incident must be open.<br /><br />An incident cannot have more than 1000 alerts. The server will return an error if merging the source incidents<br />will result in the target incident having more than 1000 alerts.<br /><br />Scoped OAuth requires: `incidents.write`<br />
`snooze`	`exec`	`id`	`From`	Snooze an incident.<br /><br />An incident represents a problem or an issue that needs to be addressed and resolved.<br /><br />For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents)<br /><br />Scoped OAuth requires: `incidents.write`<br /><br /><br />StackQL: call this method with the raw JSON body, for example `EXEC incidents.incidents.snooze @id = '...' @@json='{"duration": <integer>}'` - the duration attribute is integer-typed, which the EXEC parameter form does not accept.

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 resource.
`From`	`string (email)`	The email address of a valid user associated with the account making the request.
`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 used to render timestamps and to interpret `since/until` values before filtering. Rendering defaults to UTC if omitted. `since/until` default to the account's time zone if omitted.
`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`	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
list

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](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents) Scoped OAuth requires: incidents.read

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

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](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents) Scoped OAuth requires: incidents.read

SELECT
id,
acknowledgements,
alert_counts,
alert_grouping,
assigned_via,
assignments,
body,
conference_bridge,
created_at,
escalation_policy,
first_trigger_log_entry,
html_url,
incident_key,
incident_number,
incident_type,
incidents_responders,
is_mergeable,
last_status_change_at,
last_status_change_by,
pending_actions,
priority,
resolve_reason,
resolved_at,
responder_requests,
self,
service,
status,
summary,
teams,
title,
type,
updated_at,
urgency
FROM pagerduty.incidents.incidents
WHERE 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
Manifest

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](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents) Scoped OAuth requires: incidents.write This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.

INSERT INTO pagerduty.incidents.incidents (
incident,
"From"
)
SELECT 
'{{ incident }}' /* required */,
'{{ From }}'
RETURNING
incident
;

# Description fields are for documentation purposes
- name: incidents
props:
  - name: incident
    description: |
      Details of the incident to be created.
    value:
      type: "{{ type }}"
      title: "{{ title }}"
      service:
        id: "{{ id }}"
        summary: "{{ summary }}"
        type: "{{ type }}"
        self: "{{ self }}"
        html_url: "{{ html_url }}"
      priority:
        id: "{{ id }}"
        summary: "{{ summary }}"
        type: "{{ type }}"
        self: "{{ self }}"
        html_url: "{{ html_url }}"
      urgency: "{{ urgency }}"
      body:
        details: "{{ details }}"
      incident_key: "{{ incident_key }}"
      assignments:
        - assignee:
            id: "{{ id }}"
            summary: "{{ summary }}"
            type: "{{ type }}"
            self: "{{ self }}"
            html_url: "{{ html_url }}"
      incident_type:
        id: "{{ id }}"
        name: "{{ name }}"
      escalation_policy:
        id: "{{ id }}"
        summary: "{{ summary }}"
        type: "{{ type }}"
        self: "{{ self }}"
        html_url: "{{ html_url }}"
      conference_bridge:
        conference_number: "{{ conference_number }}"
        conference_url: "{{ conference_url }}"
  - name: From
    value: "{{ From }}"
    description: The email address of a valid user associated with the account making the request.
    description: The email address of a valid user associated with the account making the request.

`UPDATE` examples

update

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](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents) Scoped OAuth requires: incidents.write

UPDATE pagerduty.incidents.incidents
SET 
incident = '{{ incident }}'
WHERE 
id = '{{ id }}' --required
AND incident = '{{ incident }}' --required
AND From = '{{ From}}'
RETURNING
incident;

Lifecycle Methods

update_bulk
merge
snooze

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). For more information see the [API Concepts Document](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents) Scoped OAuth requires: incidents.write This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.

EXEC pagerduty.incidents.incidents.update_bulk 
@limit='{{ limit }}', 
@offset='{{ offset }}', 
@total={{ total }}, 
@From='{{ From }}' 
@@json=
'{
"incidents": "{{ incidents }}"
}'
;

Merge a list of source incidents into the target [incident](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents). After the merge is performed the target incident will contain the source incidents' [alerts](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#alerts), and the source incidents will be resolved. Only incidents that have alerts or incidents that were created manually in the UI can be merged. Open incidents cannot be merged into a resolved incident. The target incident must be open. An incident cannot have more than 1000 alerts. The server will return an error if merging the source incidents will result in the target incident having more than 1000 alerts. Scoped OAuth requires: incidents.write

EXEC pagerduty.incidents.incidents.merge 
@id='{{ id }}' --required, 
@From='{{ From }}' 
@@json=
'{
"source_incidents": "{{ source_incidents }}"
}'
;

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](https://developer.pagerduty.com/api-reference/a47605517c19a-api-concepts#incidents) Scoped OAuth requires: incidents.write StackQL: call this method with the raw JSON body, for example EXEC incidents.incidents.snooze @id = '...' @@json='{"duration": <integer>}' - the duration attribute is integer-typed, which the EXEC parameter form does not accept.

EXEC pagerduty.incidents.incidents.snooze 
@id='{{ id }}' --required, 
@From='{{ From }}' 
@@json=
'{
"duration": {{ duration }}
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

Lifecycle Methods​