PagerDuty Toolkit

The PagerDuty toolkit connects a PagerDuty account to agents and workflows using a REST API token and lets you list and manage incidents, create and resolve incidents, look up services and users, and find the current on-call responder for a schedule or service.

Prerequisites

• An active PagerDuty account with at least one service.
• A PagerDuty REST API token — go to Integrations → API Access Keys in PagerDuty and create a General Access or User Token.
• A Default From Email — the exact email address of a PagerDuty user who is allowed to create, acknowledge, and resolve incidents. PagerDuty requires this for all incident write actions.
• Schedule IDs for on-call lookups, and service IDs for incident filters and creation. Use List Services and List Users to discover these.

aviso

Write actions (Acknowledge Incident, Resolve Incident, Create Incident) change live PagerDuty data immediately. Confirm the incident ID, service, and intended outcome before running them. Avoid automatic retries on Create Incident — uncertain responses can create duplicate incidents. Never expose the API token in prompts, chat, tickets, screenshots, or documentation.

Setup

1. Create a PagerDuty REST API token

   In PagerDuty, go to Integrations → API Access Keys and create a General Access or User Token. Copy it immediately and store it securely.

2. Identify the Default From Email

   Go to People → Users in PagerDuty and find the email address of a user allowed to manage incidents. You will need this exact address for all incident write actions.

3. Open an agent or workflow

   Open an agent and add the PagerDuty toolkit under Toolkits, or add a PagerDuty step to a workflow.

4. Create a saved connection

   In the PagerDuty step, choose + New under Select saved connection. Enter a Connection Name, the API Token, and the Default From Email. Save the connection.

5. Test with a read action first

   Run List Services or List Incidents to confirm access before using incident write actions. For agents, use the Test Connection button to verify authentication.

Available tools

Incident Retrieval

Tool	Description
List Incidents	Lists incidents with optional filters for status, urgency, service, assignee, and date range. Returns up to 100 incidents per page.
Get Incident	Returns one incident by ID including service, assignments, acknowledgements, escalation policy, and alerts.

Incident Management

Tool	Description
Acknowledge Incident	Changes a triggered incident to acknowledged. Uses the Default From Email unless overridden.
Resolve Incident	Changes an incident to resolved with an optional resolution note. Uses the Default From Email unless overridden.
Create Incident	Creates a new incident for a specified service with optional urgency and details. Uses the Default From Email unless overridden.

Service and User Discovery

Tool	Description
List Services	Lists PagerDuty services with optional name and integration type filters. Use to discover service IDs.
List Users	Lists PagerDuty users with optional name/email and role filters. Use to discover user IDs for assignee filters.

On-Call

Tool	Description
Get On-Call	Returns current on-call entries for a schedule or a service's escalation policy. Provide at least one of Schedule ID or Service ID.

Use cases

• List all triggered high-urgency incidents for a production service and surface them in a standup summary.
• Find the current on-call responder for a service and include their name and email in a downstream notification.
• Automatically acknowledge an incident after an operator accepts ownership in an approval step.
• Create a high-urgency incident when an automated monitoring step detects a critical service failure.
• Resolve an incident and add a resolution note after a health-check step confirms recovery.

Troubleshooting

Symptom	Likely cause	Fix
Invalid or unauthorized API token	The token was copied incorrectly, has been revoked, or lacks access to the required resources.	Create a new token and update the connection.
Write actions fail with From Email error	The Default From Email is not a valid PagerDuty user, or the user cannot manage incidents.	Confirm the email belongs to a PagerDuty user in the same account who is allowed to create and update incidents.
Incident, service, schedule, or user not found	A display name was used instead of a resource ID, or the token cannot access that resource.	Use List Services or List Users to find accessible IDs. Always use PagerDuty resource IDs, not display names.
Get On-Call returns no users	No active schedule layer or escalation target applies at the current time.	Confirm the schedule has an active layer and the service has an escalation policy with an active on-call target. Check the schedule timezone and any active override rules.
List Incidents returns no results	Filters are too restrictive or the token cannot see any incidents.	Remove optional status, urgency, service, assignee, or date filters and retry. Confirm Since and Until use valid ISO 8601 values.
PagerDuty rate limit errors (429)	Too many requests were made in a short window.	Rate-limit responses are retried automatically. Reduce repeated calls and wait before testing again if the issue persists.