> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PagerDuty

Our PagerDuty integration allows [Agents](/concepts/agents) to learn about, filter, and
take action on incidents happening in your infrastructure.

<AccordionGroup>
  <Accordion title="MCP Tools" icon="wrench">
    * **pagerduty\_get\_incident\_details**: Retrieve incident details by ID
    * **pagerduty\_get\_alert\_details\_for\_incident**: Get alert details for an incident
    * **pagerduty\_post\_status\_update**: Post a status update to an incident
    * **pagerduty\_resolve\_incident**: Resolve an incident
  </Accordion>
</AccordionGroup>

## Prerequisites

To configure the PagerDuty integration you'll need to generate a PagerDuty
API key.

<Steps>
  <Step title="Open your PagerDuty 'User Settings' page">
    In the top right corner of the PagerDuty UI, hover over your profile image
    and click on "My Profile".

    Then open the "User Settings" tab:

    <img src="https://mintcdn.com/aptible-bot/5SAJPYW5AZAq0sFG/images/pagerduty/user-settings.png?fit=max&auto=format&n=5SAJPYW5AZAq0sFG&q=85&s=db7fe8a12fa35ae6ef3e63544bc04d97" alt="PagerDuty User Settings" width="2066" height="898" data-path="images/pagerduty/user-settings.png" />
  </Step>

  <Step title="Generate API Token">
    Click on "Create API User Token":

    <img src="https://mintcdn.com/aptible-bot/5SAJPYW5AZAq0sFG/images/pagerduty/user-token.png?fit=max&auto=format&n=5SAJPYW5AZAq0sFG&q=85&s=9066a5d295d5b4faf8f453096aa19b0c" alt="PagerDuty API Token" width="1238" height="686" data-path="images/pagerduty/user-token.png" />
  </Step>
</Steps>

## Configuration

Configure the PagerDuty plugin by running `uv run unpage configure` or by editing
the `~/.unpage/profiles/<profile_name>/config.yaml` file:

```yaml theme={null}
plugins:
  # ...
  pagerduty:
    enabled: true
    settings:
      api_key: <your api key> # required
      from_email: <email address for status updates> # optional
```

## Developing Agents

Your Agents can react to PagerDuty incidents by adding context from your
[Knowledge Graph](/concepts/knowledge-graph), pulling [Metrics](/plugins/metrics),
or running custom [Shell Commands](/plugins/shell).

Learn more about [Creating Agents](/concepts/agents).

### Running Locally

You can test your Agents locally on past or current PagerDuty incidents by
passing in a PagerDuty incident URL as the payload to `unpage agent run`:

```bash theme={null}
uv run unpage agent run <agent_name> https://youraccount.pagerduty.com/incidents/Q179JHZ8AMBVDO
```

Unpage will fetch the incident automatically and send it to your Agent. The
Agent thought process, tool calls, and output will be printed to `stdout`.

### Webhooks

Agent workflows can run automatically by configuring PagerDuty to send webhooks
to your [Unpage Server](/commands/agent#subcommand%3A-serve).

<Steps>
  <Step title="Open the PagerDuty Webhooks page">
    In the top navigation hover over "Integrations" and then click on
    "Generic Webhooks (v3)".
  </Step>

  <Step title="Add a New Webhook">
    Click on "+ New Webhook"

    The **Webhook URL** should be the hostname of your running Unpage Server,
    with a path of `/webhook` (like `https://unpage.yourdomain.com/webhook`).

    During development you can tunnel to your local Unpage instance using ngrok by
    running `uv run unpage agent serve --tunnel` (see [Unpage Server](/commands/agent#subcommand%3A-serve)
    for details).

    The **Event Subscriptions** should be whatever events you want to run Agent
    workflows on, for example `incident.triggered`.
  </Step>
</Steps>

Unpage will now receive webhooks from PagerDuty and send them to the
[Router](/concepts/router), which will decide which [Agent](/concepts/agents) workflow to run.

<Info>
  For production deployments with PagerDuty integration, see our [Deployment Guide](/howto/deployment-guide) for complete setup instructions including Docker configuration and GitHub Actions CI/CD.
</Info>

## Tools

The PagerDuty plugin provides the following tools to Agents and MCP Clients:

<Card title="pagerduty_get_incident_details">
  Get a PagerDuty incident by ID, including all alert details.

  **Arguments**

  <ParamField path="incident_id" type="string" required>
    The ID of the PagerDuty incident. Typically a string of uppercase letters and
    numbers. For example "PGR0VU2", "PF9KMXH", or "Q2K78SNJ5U1VE1".
  </ParamField>

  **Returns** `dict`: The incident JSON payload, including all alert details.
</Card>

<br />

<Card title="pagerduty_get_alert_details_for_incident">
  Get the details of the alert(s) for a PagerDuty incident.

  **Arguments**

  <ParamField path="incident_id" type="string" required>
    The ID of the PagerDuty incident. Typically a string of uppercase letters and
    numbers. For example "PGR0VU2", "PF9KMXH", or "Q2K78SNJ5U1VE1".
  </ParamField>

  **Returns** `list[dict]`: The list of alert details.
</Card>

<br />

<Card title="pagerduty_post_status_update">
  Post a status update to a PagerDuty incident.

  **Arguments**

  <ParamField path="incident_id" type="string" required>
    The ID of the PagerDuty incident. Typically a string of uppercase letters and
    numbers. For example "PGR0VU2", "PF9KMXH", or "Q2K78SNJ5U1VE1".
  </ParamField>

  <ParamField path="message" type="string" required>
    The status update to post.
  </ParamField>

  **Returns** `None`
</Card>

<br />

<Card title="pagerduty_resolve_incident">
  Resolve a PagerDuty incident.

  **Arguments**

  <ParamField path="incident_id" type="string" required>
    The ID of the PagerDuty incident. Typically a string of uppercase letters and
    numbers. For example "PGR0VU2", "PF9KMXH", or "Q2K78SNJ5U1VE1".
  </ParamField>

  <ParamField path="resolution_message" type="string">
    An optional message to include with the resolution.
  </ParamField>

  **Returns** `None`
</Card>