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

# Acknowledgment and Handoff

> Acknowledge an incident to stop escalation, or hand it off to another responder when you can't take it.

When an incident pages you, two actions decide what happens next: **acknowledging** the page stops further escalation; **handing off** transfers the lead to another team member.

<Frame caption="Acknowledge and handoff controls on the incident detail page">
  <img src="https://mintcdn.com/scalingcloud/5-FlXcH6ySIwHzG0/images/placeholder.svg?fit=max&auto=format&n=5-FlXcH6ySIwHzG0&q=85&s=18ab9c45531fe92b117df1f9652cb357" alt="Acknowledgment panel" width="1200" height="675" data-path="images/placeholder.svg" />
</Frame>

## Acknowledging an incident

Acknowledging tells scaling.cloud you are on it. It does two things:

1. **Cancels the next escalation timeout** — scaling.cloud will not page the next layer of the escalation policy.
2. **Records who took the page** — your user is recorded as the acknowledger on the incident's audit trail.

Acknowledging does **not** change the incident's status. The incident stays in `investigating` (or whichever status it is in) until you progress it to `identified`, `monitoring`, or `resolved`.

### Where you can acknowledge

| Surface    | How                                                                                   |
| ---------- | ------------------------------------------------------------------------------------- |
| Dashboard  | Click **Acknowledge** in the incident escalation panel.                               |
| Slack      | Click the **Acknowledge** button on the alert message (DM or channel).                |
| SMS reply  | **Reply the short code** from the SMS page (e.g. `K7Q3M`) from your verified number.  |
| Phone call | **Answer** the automated voice call — a live answer acknowledges; voicemail does not. |
| API        | `POST /v1/incidents/{id}/acknowledge`                                                 |
| Public API | `POST /v1/incidents/{id}/acknowledge` with your API key.                              |

```bash theme={null}
curl -X POST https://api.scaling.cloud/v1/incidents/{incidentId}/acknowledge \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Note>
  Acknowledgment is **idempotent**. Calling acknowledge on an incident that is
  already acknowledged returns success without doing anything; calling
  acknowledge on a `resolved` incident is a no-op.
</Note>

### Acknowledging from your phone, no app

If you're paged on a [contact method](/concepts/contact-methods), you can acknowledge without opening scaling.cloud at all:

* **Reply to the SMS.** Every SMS page ends with `Or reply <CODE> to ack`. Text that short code back **from the verified number that was paged** and the incident acknowledges — escalation stops. The reply only works from your own verified number, and the code stops working once the page is acknowledged or escalation has already moved past your layer. An unknown or stale code is ignored.
* **Answer the voice call.** Answering the automated call acknowledges it — there's no keypress. If the call goes to voicemail it's recorded as delivery only, and escalation continues to the next layer.

<Note>
  Both phone paths converge on the **same acknowledgment** as the dashboard and
  API — they cancel the escalation timer and record you as the acknowledger on
  the audit trail. Acknowledging is always reversible by [handing
  off](#handing-off-an-incident).
</Note>

## Handing off an incident

If you can't take a page — you are heads-down on another incident, off duty, or out of context — hand it off to someone else. The handoff:

1. Updates the **lead** of the incident to the target user.
2. Pages the **target user** through the same notification channels (email, Slack).
3. Records the **handoff** on the audit trail with both the previous and new lead.

The target user must be a member of your organization. You cannot hand off to someone outside the org.

### Handing off from the dashboard

<Steps>
  <Step title="Open the incident">
    Navigate to the incident detail page and find the **Escalation** panel.
  </Step>

  <Step title="Choose a recipient">
    In the handoff form, select another org member from the list.
  </Step>

  <Step title="Submit">
    Click **Hand off**. The new lead is paged immediately and you stop receiving
    escalation pings.
  </Step>
</Steps>

### Handing off via the API

```bash theme={null}
curl -X POST https://api.scaling.cloud/v1/incidents/{incidentId}/handoff \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetUserId": "user_2xyz..."}'
```

<Warning>
  A handoff resets escalation back to a single notified responder — the new
  lead. If the new lead doesn't acknowledge within the current layer's
  `ackTimeoutMinutes`, escalation resumes from where it left off.
</Warning>

## Audit trail

Both actions are recorded on the incident's paging audit trail with the actor, timestamp, and (for handoffs) the previous and new lead. The audit trail is available on the incident detail page and via the API on the incident record.

<Tip>
  Acknowledge first, even if you plan to hand off. Acknowledging stops the
  escalation clock and gives you a moment to figure out who is the right next
  person.
</Tip>