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

# PagerDuty

> Connect PagerDuty so HealOps can surface active incidents and on-call context during investigations

HealOps queries PagerDuty to retrieve triggered and acknowledged incidents, full incident timelines, and current on-call schedules — giving the AI agent the incident management context it needs to produce faster, more accurate root-cause analyses.

## What HealOps fetches

| Tool                  | What it does                                                                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `pagerduty_incidents` | Lists active incidents (triggered/acknowledged), searches by service or time range, fetches full incident detail and timeline log entries |
| `pagerduty_oncall`    | Identifies who is currently on-call for an escalation policy or schedule                                                                  |

## Prerequisites

* A PagerDuty account with REST API v2 access
* A PagerDuty API key (User token or service account) with at minimum **Read** access

## Creating an API key

1. Log into PagerDuty → **User Icon** → **My Profile** → **User Settings** → **Create API User Token**
2. Give the token a descriptive name (e.g. `healops-readonly`)
3. Copy the token — it is only shown once

For production use, prefer a [Service Account](https://support.pagerduty.com/docs/service-accounts) with Read-Only permissions.

## Setup

### Option 1: Interactive CLI

```bash theme={null}
healops integrations setup pagerduty
```

The wizard will ask for your **PagerDuty API key**.

### Option 2: Environment variables

Add to your `.env`:

```bash theme={null}
PAGERDUTY_API_KEY=your_api_key_here

# Optional: override the base URL (only needed for on-prem or EU deployments)
# PAGERDUTY_BASE_URL=https://api.pagerduty.com
```

| Variable             | Default                     | Description                                       |
| -------------------- | --------------------------- | ------------------------------------------------- |
| `PAGERDUTY_API_KEY`  | —                           | **Required.** PagerDuty REST API v2 token         |
| `PAGERDUTY_BASE_URL` | `https://api.pagerduty.com` | Base URL (override for EU or private deployments) |

### Option 3: Persistent store

```json theme={null}
{
  "version": 1,
  "integrations": [
    {
      "id": "pagerduty-prod",
      "service": "pagerduty",
      "status": "active",
      "credentials": {
        "api_key": "your_api_key_here"
      }
    }
  ]
}
```

## Verify

```bash theme={null}
healops integrations verify pagerduty
```

A successful verification prints the word `passed` and confirms the API key is accepted.

## Tool reference

### `pagerduty_incidents`

Lists or searches PagerDuty incidents. Optionally fetches full detail and timeline log entries for a specific incident.

| Parameter     | Type      | Default                        | Description                                                             |
| ------------- | --------- | ------------------------------ | ----------------------------------------------------------------------- |
| `api_key`     | string    | —                              | **Required.** PagerDuty API key                                         |
| `statuses`    | string\[] | `["triggered","acknowledged"]` | Filter by status: `triggered`, `acknowledged`, `resolved`               |
| `service_ids` | string\[] | `[]`                           | Limit to specific PagerDuty service IDs                                 |
| `since`       | string    | —                              | ISO 8601 start time for time-range filter (e.g. `2026-05-19T00:00:00Z`) |
| `until`       | string    | —                              | ISO 8601 end time for time-range filter                                 |
| `incident_id` | string    | —                              | Fetch full detail + log entries for a specific incident ID              |
| `limit`       | integer   | `25`                           | Maximum number of incidents to return (max 100)                         |

#### Example: all triggered incidents

```python theme={null}
{
  "api_key": "...",
  "statuses": ["triggered"],
  "limit": 10
}
```

#### Example: full detail for a specific incident

```python theme={null}
{
  "api_key": "...",
  "incident_id": "P12ABCDE"
}
```

### `pagerduty_oncall`

Returns the current on-call roster, optionally filtered by escalation policy or schedule.

| Parameter               | Type      | Default | Description                     |
| ----------------------- | --------- | ------- | ------------------------------- |
| `api_key`               | string    | —       | **Required.** PagerDuty API key |
| `escalation_policy_ids` | string\[] | `[]`    | Filter by escalation policy IDs |
| `schedule_ids`          | string\[] | `[]`    | Filter by schedule IDs          |

#### Example: on-call for a specific policy

```python theme={null}
{
  "api_key": "...",
  "escalation_policy_ids": ["POLICY_ID"]
}
```

## RCA integration

When PagerDuty is configured, the investigation pipeline automatically:

1. Fetches the currently triggered/acknowledged incidents to establish incident context
2. Fetches the on-call schedule to identify who is responsible for the affected service
3. Includes incident timeline log entries in the RCA summary

This context surfaces in the AI agent's investigation alongside signals from Datadog, Sentry, CloudWatch, or other observability integrations.

## Troubleshooting

**`auth_error`** — The API key is invalid or has been revoked. Generate a new token in PagerDuty and update your `.env`.

**`HTTP 403`** — Your API key lacks the required scope. Ensure the token has at minimum Read access to Incidents and On-Call data.

**Empty incident list** — If no incidents are returned, check that your `statuses` filter matches what is in PagerDuty and that the `since`/`until` time range covers the window you expect.