PagerDuty Incidents
Lets an agent work PagerDuty incidents: see who is on call, list and read open incidents with their alerts, timeline and notes, add notes, acknowledge, resolve or reassign incidents, and open a new incident on a service. Curated from PagerDuty's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with PagerDuty Incidents via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /users/me |
getCurrentUser | Get the user that owns the API token |
| GET | /oncalls |
listOnCalls | See who is on call, per schedule and escalation policy |
| GET | /services |
listServices | List services, optionally filtered by name |
| GET | /services/{id} |
getService | Get a service and its escalation policy |
| GET | /incidents |
listIncidents | List incidents by status, service, urgency or date |
| POST | /incidents |
createIncident | Open a new incident on a service (pages the on-call) |
| GET | /incidents/{id} |
getIncident | Get an incident's status, assignees and service |
| PUT | /incidents/{id} |
updateIncident | Acknowledge, resolve, reassign or change urgency of an incident |
| GET | /incidents/{id}/alerts |
listIncidentAlerts | List the alerts grouped into an incident |
| GET | /incidents/{id}/log_entries |
listIncidentLogEntries | Get an incident's timeline (triggers, notifications, acks) |
| GET | /incidents/{id}/notes |
listIncidentNotes | List notes on an incident |
| POST | /incidents/{id}/notes |
createIncidentNote | Add a note to an incident |
Authentication
apiToken
API key — sent as the Authorization header
PagerDuty REST API key, sent as Authorization: Token token=<key>.
How to get a credential
- User token (recommended): in PagerDuty open My Profile > User Settings > Create API User Token. It acts as you and respects your role.
- Account key (admins): Integrations > API Access Keys > Create New API Key. Untick Read-only if the agent must acknowledge, resolve or create incidents.
- Copy the key (shown once) and enter the credential value as
Token token=<your-key>.
Permissions used
REST API keys are not scoped per endpoint; access follows the key type and your role.
| Access | Operations |
|---|---|
| Read | getCurrentUser (user token only), listIncidents, getIncident, listIncidentAlerts, listIncidentLogEntries, listIncidentNotes, listOnCalls, listServices, getService |
| Write (not read-only) | createIncident, updateIncident, createIncidentNote |
Common errors
- 401 Unauthorized: the value must be
Token token=<key>(notBearer), or the key was revoked. - 403 Forbidden: a read-only key was used for a write, or your role cannot see that team's incidents.
- 400 Bad Request: the
Fromheader is missing or is not the email of a PagerDuty user (required on writes with account keys), or the body is malformed. - 429 Too Many Requests: about 960 requests/minute per key; back off and retry after a few seconds.
Store the key as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add a PagerDuty REST API key as the credential, entered as
Token token=<key>(a user token is best: actions are logged under your name). - Preset
Fromto the email of your PagerDuty user. Write operations (updateIncident,createIncident,createIncidentNote) require it. Acceptis pinned toapplication/vnd.pagerduty+json;version=2; leave it as is.
Respond to an incident
listOnCalls(optionallyschedule_ids[],escalation_policy_ids[],earliest=true) to see who is on call now.listIncidentswithstatuses[]=triggeredandstatuses[]=acknowledged(optionallyservice_ids[],urgencies[]=high,since/until) to find open incidents.getIncidentwith the incidentidfor title, status, urgency, service and assignees.listIncidentAlertsfor the raw alert details,listIncidentLogEntries(is_overview=truefor a short timeline), andlistIncidentNotesfor what responders already wrote.createIncidentNotewith{"note": {"content": "..."}}to record findings.- Show the user the planned change and wait for confirmation, then
updateIncidentwith{"incident": {"type": "incident_reference", "status": "acknowledged"}}or"resolved"(addresolution). Reassign withassignments: [{"assignee": {"id": "<user id>", "type": "user_reference"}}], or changeurgency/escalation_level.
Open a new incident
listServiceswithquery(service name) to get the service id.- Confirm with the user first: a new incident pages the on-call responder.
createIncidentwith{"incident": {"type": "incident", "title": "...", "service": {"id": "<service id>", "type": "service_reference"}, "urgency": "high", "body": {"type": "incident_body", "details": "..."}}}. Addincident_keyto avoid duplicates.
Good to know
- Ids are short strings like
PABC123; the incidentincident_numberis the human number shown in the UI. - Times are ISO 8601 (e.g.
2026-10-14T08:00:00Z);since/untilcover at most 6 months. - Lists use
limit(max 100) andoffset; checkmorein the response for another page. getCurrentUseronly works with a user token, not an account-level key.- This spec cannot delete or merge incidents or change services.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “PagerDuty Incidents” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.