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

# Cancel responder requests for an incident

`PUT https://api.pagerduty.com/incidents/{id}/responder_requests/cancel`

Cancel pending responder requests for the specified incident.

This endpoint allows you to cancel responder requests for specified targets that are in a pending state. Only responders who have not yet joined or declined can be cancelled. This endpoint requires the account to have access to the [responder requests](https://support.pagerduty.com/main/docs/add-responders) feature.

**Account Ability Requirement**: The account must have the `coordinated_responding` ability. Returns 402 Payment Required if the ability is missing. You can use the [List Abilities API](https://docs.pagerduty.com/developer/api/reference/rest/abilities/list-abilities) to check account abilities.

**State Constraints**: Only responders in the `pending` state can be cancelled. Responders who have already `joined` or `declined` are not affected (the result will indicate their current state).

**User vs Escalation Policy Behavior**:
- **Users**: Direct cancellation, updates state to `user_cancelled`, stops notifications
- **Escalation Policies**: Stops the escalation process, updates state of all pending users from that escalation policy to `user_cancelled` and stops notifications

**Result Values**:
- `cancelled`: Successfully cancelled
- `joined`: User already joined (not cancelled)
- `declined`: User already declined (not cancelled)
- `not_found`: Target not found or not part of any responder request

Scoped OAuth requires: `incidents.write`

## Authorization

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

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | The ID of the resource. |

## 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`. |

## Request body (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `requester_id` | string | yes | The user id of the requester. |
| `responder_request_targets` | array of object | yes | The array of targets to cancel. |
| `responder_request_targets[].type` | string | yes | The type of target (either a user or an escalation policy) One of: `user_reference`, `escalation_policy_reference`. |
| `responder_request_targets[].id` | string | yes | The id of the user or escalation policy. |

Example: Request Example

```json
{
  "requester_id": "PL1JMK5",
  "responder_request_targets": [
    {
      "type": "user_reference",
      "id": "PJ25ZYX"
    },
    {
      "type": "escalation_policy_reference",
      "id": "PEP12AB"
    }
  ]
}
```

## Response 200

The result of cancelling responder requests for the given incident.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `responder_request_targets` | array of object | yes | The array of targets with their cancellation results. |
| `responder_request_targets[].type` | string | yes | The type of target (either a user or an escalation policy) One of: `user_reference`, `escalation_policy_reference`. |
| `responder_request_targets[].id` | string | yes | The id of the user or escalation policy. |
| `responder_request_targets[].result` | string | yes | The result of the cancellation attempt. One of: `cancelled`, `joined`, `declined`, `not_found`. |

Example: All Targets Cancelled

```json
{
  "responder_request_targets": [
    {
      "type": "user_reference",
      "id": "PJ25ZYX",
      "result": "cancelled"
    },
    {
      "type": "escalation_policy_reference",
      "id": "PEP12AB",
      "result": "cancelled"
    }
  ]
}
```

Example: Mixed Results

```json
{
  "responder_request_targets": [
    {
      "type": "user_reference",
      "id": "PJ25ZYX",
      "result": "cancelled"
    },
    {
      "type": "user_reference",
      "id": "PL7A2O4",
      "result": "joined"
    },
    {
      "type": "user_reference",
      "id": "PABC123",
      "result": "not_found"
    }
  ]
}
```

## 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 402

Account does not have the abilities to perform the action. Please review the response for the required abilities.
You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account.

### `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 404

The requested resource was not found.

### `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. |

## 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).