> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PagerDuty Toolkit
> Connect PagerDuty to agents and workflows to manage incidents, inspect services, find on-call responders, and look up users.
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.
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
In PagerDuty, go to **Integrations → API Access Keys** and create a General Access or User Token. Copy it immediately and store it securely.
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.
Open an agent and add the **PagerDuty** toolkit under Toolkits, or add a PagerDuty step to a workflow.
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.
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. |