---
title: "Merge Incidents"
description: "Merges one Incident Management incident into another: its alerts and timeline move over, and the merged incident stops escalating."
---

`POST /api/im/incidents/:id/merge`

Merges the incident `:id` (the source) into `targetIncidentId`, for example when two alerts turned out to be the same outage. In one step:

- all alerts and timeline events of the source move to the target,
- the source gets status `merged` and `mergedIntoId` set to the target, and its escalation stops,
- the source's timeline records `merged`, the target's records `merge_received`.

Role assignments stay on the source. A merge cannot be undone through the API.

## Authentication

Any IM-eligible role (`admin`, `editor`, `responder`) or an organization-wide API token, see [Authentication](/api/incident-management#authentication). Incident Management must be enabled for the organization.

Restricted to the source incident's team: you must be a member of the team of incident `:id` or an organization admin. An organization-wide API token passes as an organization admin.

## Request Body

| Field | Type | Required | Description |
|-------|------|----------|--------------|
| `targetIncidentId` | number | Yes | The incident to merge into. Must belong to the same organization, and must be neither `merged` nor `resolved`. |

## Example (cURL)

```bash
curl -X POST "$BASE_URL/api/im/incidents/43/merge" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "targetIncidentId": 42 }'
```

## Response

`200 OK`: the updated source incident row (same shape as the `items` of [List Incidents](/api/incident-management/list-incidents), without the enrichment fields) and the target ID.

```json
{
  "source": {
    "id": 43,
    "teamId": 3,
    "title": "Replica lag above threshold",
    "status": "merged",
    "mergedIntoId": 42,
    "currentTier": null,
    "escalationEpoch": 1
  },
  "targetIncidentId": 42
}
```

(`source` shortened; the full row is returned.)

## Common errors

- `401 Unauthorized` when not authenticated
- `403 Forbidden` (`customerScopedTokenForbidden`) when using a customer-scoped token
- `403 Forbidden` (`imAccessDenied`) when the session user has no IM-eligible role
- `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization
- `403 Forbidden` (`imTeamMembershipRequired`) when you are neither a member of the source incident's team nor an organization admin
- `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or `targetIncidentId` is missing or not a positive integer
- `404 Not Found` (`imIncidentNotFound`) when the source or the target incident does not exist, or belongs to another organization
- `422 Unprocessable Entity` (`imIncidentCannotMergeIntoSelf`) when `targetIncidentId` equals `:id`
- `422 Unprocessable Entity` (`imIncidentAlreadyMerged`) when the source incident is already `merged`
- `422 Unprocessable Entity` (`imIncidentTargetAlreadyMerged`) when the target incident is `merged`
- `422 Unprocessable Entity` (`imMergeTargetClosed`) when the target incident is `resolved`