> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# List recommended rules

`GET https://api.pagerduty.com/recommendations/event_orchestrations/rules`

List AI-generated recommended rules available for an account's Service Event Orchestrations.

Results can be filtered by service or team. Use cursor-based pagination to retrieve large result sets.

Note: `service_id` and `service_ids[]` cannot be used together in the same request.

Scoped OAuth requires: `recommendations.read`

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `service_id` | string |  | Filter recommended rules for a single service. Cannot be combined with `service_ids[]`. |
| `service_ids[]` | array of string |  | Filter recommended rules for multiple services. Cannot be combined with `service_id`. Items must be unique. |
| `team_ids[]` | array of string |  | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. |
| `actions[]` | array of string |  | Filter recommended rules by action type. Items must be unique. |
| `limit` | integer |  | The number of results per page. Default: `25`. Minimum: 1. Maximum: 50. |
| `cursor` | string |  | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Response 200

A list of recommended rules for the account's Service Event Orchestrations.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `recommended_rules` | array of object |  |  |
| `recommended_rules[].recommendation_id` | string |  | The unique identifier for this recommendation (rule instance hash). Read-only. |
| `recommended_rules[].type` | string |  | The type of resource this recommendation applies to. Read-only. One of: `service`. |
| `recommended_rules[].status` | string |  | The availability status of the recommendation. Read-only. One of: `available`. |
| `recommended_rules[].description` | string |  | A human-readable description of what the recommended rule does. |
| `recommended_rules[].pcl_expr` | string |  | The PagerDuty Condition Language (PCL) expression that defines the rule's matching condition. |
| `recommended_rules[].created_at` | string (date-time) |  | The date/time the recommendation was created. Read-only. |
| `recommended_rules[].updated_at` | string (date-time) |  | The date/time the recommendation was last updated. Read-only. |
| `recommended_rules[].metrics` | object |  | Performance metrics describing the recommendation's historical match rate and effectiveness. Read-only. |
| `recommended_rules[].metrics.num_events_matching_rule` | integer |  | Total number of events that match the rule's condition. |
| `recommended_rules[].metrics.num_events_with_action` | integer |  | Total number of events that had the recommended action applied. |
| `recommended_rules[].metrics.num_events_with_action_matching_rule` | integer |  | Number of events that both match the condition and had the action applied. |
| `recommended_rules[].metrics.precision_metric` | number (float) |  | Fraction of events matching the rule that also had the action applied. Value between 0 and 1. Minimum: 0. Maximum: 1. |
| `recommended_rules[].metrics.recall` | number (float) |  | Fraction of events with the action applied that also match the rule condition. Value between 0 and 1. Minimum: 0. Maximum: 1. |
| `recommended_rules[].actions` | object |  | The action the recommended rule would apply when its condition is matched. One of the following action types will be present. |
| `recommended_rules[].actions.suppress` | boolean |  | If true, matching events will be suppressed. |
| `recommended_rules[].actions.severity` | string |  | Normalize the severity of matching events to this value. One of: `critical`, `high`, `warning`, `info`, `low`. |
| `recommended_rules[].actions.priority` | string |  | The ID of the priority to assign to matching incidents. |
| `recommended_rules[].parent` | object |  | The service this recommendation applies to. Read-only. |
| `recommended_rules[].parent.id` | string |  | The obfuscated ID of the service. |
| `recommended_rules[].parent.type` | string |  | The type of the parent resource. One of: `service_reference`. |
| `next_cursor` | string \| null |  | Cursor to retrieve the next page of results. Null if there are no more results. |

Example: Response Example

```json
{
  "recommended_rules": [
    {
      "recommendation_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "type": "service",
      "status": "available",
      "description": "Suppress alerts where event.summary matches 'disk usage'",
      "pcl_expr": "event.summary matches part 'disk usage'",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z",
      "metrics": {
        "num_events_matching_rule": 1200,
        "num_events_with_action": 950,
        "num_events_with_action_matching_rule": 900,
        "precision_metric": 0.75,
        "recall": 0.95
      },
      "actions": {
        "suppress": true
      },
      "parent": {
        "id": "P1ABC23",
        "type": "service_reference"
      }
    }
  ],
  "next_cursor": "eyJ2ZXJzaW9uIjoxLCJwYWdlIjoyLCJuZXh0X3JlY29tbWVuZGF0aW9uIjpudWxsfQ=="
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 401

Caller did not supply credentials or did not provide the correct credentials.
If you are using an API key, it may be invalid or your Authorization header may be malformed.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 403

Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 429

Too many requests have been made, the rate limit has been reached.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 500

Internal Server Error the PagerDuty server experienced an error.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).