Skip to main content
Tool Name: list_incidentsCategory: IncidentsMode: Read-only

​
Overview

The list_incidents tool retrieves a list of incidents from your PagerDuty account with powerful filtering options. You can filter by status, date range, service, team, user assignment, urgency, and more.

​
Parameters

​
status
list[string]
Filter incidents by status. Multiple statuses can be specified.Allowed values:
  • triggered - Newly created, unacknowledged incidents
  • acknowledged - Incidents that have been acknowledged
  • resolved - Incidents that have been resolved
Example: ["triggered", "acknowledged"]
​
since
datetime
Filter incidents created since this date/time. Use ISO 8601 format.Example: "2024-03-01T00:00:00Z"
​
until
datetime
Filter incidents created until this date/time. Use ISO 8601 format.Example: "2024-03-05T23:59:59Z"
​
user_ids
list[string]
Filter incidents assigned to specific users. Provide a list of user IDs.Example: ["PXXXXXX", "PYYYYYY"]
​
service_ids
list[string]
Filter incidents by service. Provide a list of service IDs.Example: ["PXXXXXX", "PYYYYYY"]
​
teams_ids
list[string]
Filter incidents by team. Provide a list of team IDs.Example: ["PXXXXXX", "PYYYYYY"]
​
urgencies
list[string]
Filter incidents by urgency level.Allowed values:
  • high - High urgency incidents
  • low - Low urgency incidents
Example: ["high"]
​
request_scope
string
default:"all"
Scope incidents based on the authenticated user’s context.Allowed values:
  • all - All incidents visible to the user (default)
  • teams - Incidents assigned to the user’s teams (requires user token)
  • assigned - Incidents assigned to the authenticated user (requires user token)
The teams and assigned scopes require a user-level API token. Account-level tokens will return an error.
​
limit
integer
default:"100"
Maximum number of results to return. Must be between 1 and 1000.Example: 50
​
sort_by
list[string]
Sort results by field and direction. Up to two fields can be specified, separated by comma.Allowed values:
  • incident_number:asc / incident_number:desc
  • created_at:asc / created_at:desc
  • resolved_at:asc / resolved_at:desc
  • urgency:asc / urgency:desc (requires account to have urgencies ability)
Example: ["created_at:desc", "urgency:desc"]

​
Usage Examples

​
List all triggered incidents

{
  "status": ["triggered"]
}

​
List high urgency incidents for a service

{
  "service_ids": ["PXXXXXX"],
  "urgencies": ["high"],
  "status": ["triggered", "acknowledged"]
}

​
List incidents from the last 24 hours

{
  "since": "2024-03-04T00:00:00Z",
  "until": "2024-03-05T00:00:00Z",
  "sort_by": ["created_at:desc"]
}

​
List incidents assigned to me

{
  "request_scope": "assigned",
  "status": ["triggered", "acknowledged"]
}

​
Response Format

Returns a ListResponseModel[Incident] containing a list of incident objects.
​
response
list[Incident]
List of incidents matching the query parameters.
​
id
string
The unique ID of the incident.
​
incident_number
integer
The incident number (unique across your account).
​
status
string
Current status: triggered, acknowledged, or resolved.
​
title
string
A succinct description of the incident.
​
summary
string
A short summary of the incident.
​
created_at
datetime
When the incident was first triggered.
​
updated_at
datetime
When the incident was last modified.
​
resolved_at
datetime
When the incident was resolved (null if not resolved).
​
service
ServiceReference
The service the incident is associated with.
​
assignments
list[Assignment]
List of users assigned to the incident.

​
Common Errors

Scope error with account-level authIf you use request_scope: "assigned" or request_scope: "teams" with an account-level API token, you’ll receive an error:
Cannot filter incidents by "[scope]" with account-level auth. Please provide a user token, or scope the request differently.
Solution: Use a user-level API token or set request_scope: "all".
Invalid status parameterIf you mistakenly use statuses instead of status, you’ll receive:
The correct parameter to filter by multiple Incidents statuses is "status", not "statuses"
Solution: Use status as the parameter name.

get_incident

Get details for a specific incident

manage_incidents

Update multiple incidents at once

create_incident

Create a new incident

list_incident_notes

View notes on an incident

​
Source Reference

Function: list_incidents in pagerduty_mcp/tools/incidents.py:27 Models: IncidentQuery, Incident in pagerduty_mcp/models/incidents.py

Build docs developers (and LLMs) love

Get started for freeTalk to us