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

# Escalations

> What only your team can do: approvals and questions waiting on you, requests your agent handed over, procedures that failed, and procedures a run did another way. One list, by email and webhook, each one a click from Coach.

An escalation is your agent saying your team is needed. There are five kinds:

| Kind | Raised when | Resolved when |
| - | - | - |
| `approval` | A step or run in a real conversation needs an approval only your team can give (the procedure's [approval](https://docs.guidinghand.ai/concepts/procedures.md) is `by: "team"`, or the agent doesn't let people in the chat approve) | It's decided, anywhere: the conversation, the console or the API |
| `question` | A task asks something only your team can answer | It's answered |
| `handoff` | The agent hands a request to your team from a chat (its `escalate` tool): the person asked for a person or another team, or its instructions say the request goes to someone else. It holds who the agent says should take it (`owner`) and everything it knew (`details`). The chat doesn't wait on it | You mark it handled (`dismiss`) |
| `procedure_failed` | A run that followed a procedure failed | The procedure gets a new revision (`fixed`), is deleted, or you dismiss it |
| `procedure_change` | A run that followed a procedure got the right result another way. The escalation holds the procedure rewritten to what worked (`proposal`) | You accept the proposal (it becomes the next revision), the procedure gets another revision, or you reject it |

What isn't an escalation:

* An approval or question **whoever is chatting** can answer stays in the chat.
* **Test chats never escalate**: your team's own chats in the console, the widget preview and Coach. A test chat's run shows how it went against its procedure on the task instead, with **Review in Coach**.
* **Evals** raise procedure escalations quietly: they're in the list as "from an eval", with no email, webhook or chat message.

## The procedure check

After every run that followed a procedure, a model reads the procedure (at the revision the run was given) and what the run did, and says whether it followed the steps, did it another way that worked, or failed. Nothing about the procedure changes until someone accepts a proposal or saves a new revision. A run of a revision that's since been changed isn't checked.

The check is **AI Review** on the pricing page: it runs on the cheapest model of the agent's own provider and is paid by its tokens at that model's price, like a chat reply, rounded up to the next cent (a cent or two a run). A conversation's price shows it as **AI Review**. It doesn't run when your balance is empty, and you can turn it off for an agent (below).

Repeats add up: there's one open escalation per procedure and kind, with `count` and the latest 20 runs in `tasks`.

```json theme={null}
{
  "object": "escalation",
  "id": "esc_8b1f0c2d4e6a7b9c1d",
  "agent_id": "support",
  "kind": "procedure_change",
  "status": "open",
  "source": "live",
  "summary": "Used the warranty API instead of the page: one load instead of five clicks.",
  "count": 3,
  "procedure": { "id": "prc_8fK2mQ0aLp4x", "title": "Find the warranty end date from a serial number", "revision": 3 },
  "failed_at": "2",
  "proposal": { "base_revision": 3, "body": "1. Open https://api.example.com/warranty/{serial}.\n2. Read end_date.\nCheck: the serial matches." },
  "owner": null,
  "details": null,
  "tasks": ["task_Hq2x", "task_Pz9m", "task_Ab3c"],
  "conversation_id": null,
  "request_id": null,
  "created_at": "2026-10-20T15:03:36.037Z",
  "last_seen_at": "2026-10-20T17:41:02.511Z",
  "resolved_at": null,
  "resolution": null,
  "resolved_by": null,
  "resolved_revision": null
}
```

## Escalation rules

Each agent decides what escalates, in its `escalations` setting (the console: the agent's **Escalations** tab). Every key is on by default:

| Key | Off means |
| - | - |
| `qa` | Its procedure runs aren't checked, so nothing is charged for them and no `procedure_failed` or `procedure_change` is raised. Test chats show no check either. |
| `approval`, `question` | Approvals and questions only your team can take still wait in their conversation, where you can decide them, but aren't escalated: no list entry, email or webhook. |
| `handoff` | The agent isn't offered `escalate`, so it can't hand requests to your team from a chat. |
| `procedure_failed`, `procedure_change` | Runs are still checked (and charged) while `qa` is on, and the verdict is kept on the run, but that kind isn't raised. |

```bash theme={null}
curl -X PATCH https://guidinghand.ai/v1/agents/support -H "Authorization: Bearer $EAGER_API_KEY" \
  -H "Content-Type: application/json" -d '{"escalations": {"qa": false}}'
```

Like every setting, they're part of the agent's [versions](https://docs.guidinghand.ai/concepts/agents.md#versions): a draft's rules apply once it's published. A task follows the rules of the version it ran.

## In the console

**Escalations** lists them, with the number open on its tab. Open one to:

* decide an approval or answer a question right there, in its conversation;
* **Fix in Coach** (or **Edit in Coach** for a proposal): the agent's Coach opens in a new chat that already knows what went wrong, the procedure as it is now and which runs to read, and proposes the fix;
* **Accept**, **Reject** or **Dismiss**, or **Mark handled** for a hand-off.

A procedure with an open escalation is marked in the agent's Procedures tab.

## Being told

* **Email, right away**, to the org's owners and admins: a hand-off, and an approval or question only your team can decide that's still open a minute after it was raised.
* **A daily digest** of procedure escalations raised or grown since the last one. None when nothing's new.
* **Webhooks**: `escalation.created`, `escalation.updated` (a repeat, or a new proposal) and `escalation.resolved`, with `escalation`. See [Webhooks](https://docs.guidinghand.ai/guides/webhooks.md).
* **Teams or Slack**: each new one posted as a thread in the channel you chose, with a button to resolve it and Coach a reply away. See [Teams and Slack](https://docs.guidinghand.ai/concepts/chat-apps.md).

## In the API

```bash theme={null}
curl https://guidinghand.ai/v1/escalations?status=open -H "Authorization: Bearer $EAGER_API_KEY"
curl -X POST https://guidinghand.ai/v1/escalations/esc_8b1f0c2d4e6a7b9c1d/accept -H "Authorization: Bearer $EAGER_API_KEY"
```

`GET /v1/escalations` filters by `status`, `agent_id`, `kind` and `q`, and its answer has `open_count`. `POST /v1/escalations/{id}/dismiss`, `/accept` and `/reject` resolve procedure escalations, and `dismiss` marks a hand-off handled (admins); approvals and questions are decided in their [conversation](https://docs.guidinghand.ai/concepts/conversations.md). Accepting a proposal answers `409` if the procedure changed since it was proposed. To open Coach with one, send `escalation_id` with the first message to `POST /v1/agents/{agent_id}/coach`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.