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

# Handoff Insights report

> See why the AI hands sessions to your team, grouped by the reasons it gave, and drill into missing knowledge, tools, prohibited topics and instructions.

Handoff Insights shows why the AI handed sessions to your team in a period, grouped by the reasons the AI gave, and points you at the knowledge, action, topic or instruction to change. Use it when the [Impact Dashboard](https://docs.open.cx/reports/impact-dashboard.md) shows a share of handed-off sessions you want to lower.

> [!NOTE]
>
> **Reports & Apps → Handoff Insights** in your [OpenCX dashboard](https://platform.open.cx/reports/handoff-insights). Requires **Reports: Read** in [Roles](https://docs.open.cx/security/roles.md). It isn't in the sidebar until someone adds it; see [Reports & Apps](https://docs.open.cx/reports/overview.md).

## What the report counts

Each time the AI hands a session to your team, it records one or more reasons and a short explanation. Handoffs caused by a reached usage limit are recorded too. Handoff Insights reads those records:

* **One entry per session.** If the AI hands the same session off again, the latest handoff's reasons replace the earlier ones.
* **Only AI handoffs.** Sessions a teammate takes over, or that a workflow routes to your team, are not included.
* **Period.** The range defaults to the current calendar month. Pick another range with the date picker; future dates can't be selected. Days are counted in UTC, by the time of the handoff.
* **History.** Insights cover sessions from January 10, 2025 onward.

## Read "Why handoffs happen"

Each row is one combination of reasons, for example **Missing tools + User asked for a human**, with its number of sessions and its share of all sessions in the list. The ten largest combinations are shown; the rest are summed as **+N more with other combinations**.

Hover a row and select **Ask Mo** (**Ask …'s expert** under a partner's branding) to read what is happening, a recommendation, and links to the matching drill-down or setting.

| Reason | What it means | Where to fix it |
| - | - | - |
| **Missing knowledge** | The AI searched your knowledge but couldn't find what it needed. | Add or expand content in your [knowledge sources](https://docs.open.cx/knowledge/introduction.md). |
| **Missing or insufficient tools** | The AI needed to do something, such as look up an order, but no action covered it or the action failed. | Build or fix an [action](https://docs.open.cx/actions/introduction.md). |
| **The AI followed instructions** | One of your instructions told the AI to hand off in this situation. | Review the instruction in [AI Instructions](https://docs.open.cx/ai-instructions/overview.md). |
| **Unclear instructions** | Your instructions were ambiguous or contradicted each other. | Make the rule specific in [AI Instructions](https://docs.open.cx/ai-instructions/overview.md) or your AI profile. |
| **User requested a human** | The customer asked for a person. | Require customers to try the AI first in [Settings → Handoff](https://docs.open.cx/handoff/settings.md). |
| **Prohibited topic** | The session touched a topic you marked as off-limits for the AI. | Review the list in [Handoff topics](https://docs.open.cx/handoff/topics.md). |
| **Usage limit reached** | Your monthly usage limit was reached, so the session went to your team without an AI reply. | Raise or remove the limit in [Billing](https://docs.open.cx/billing.md#when-a-limit-is-reached). |

A session can have several reasons. Fixing any one of them may not be enough: a session with **Missing knowledge + Missing tools** needs both.

## Drill into a reason

Below the list, four sections break handoffs down by what the AI pointed to. Select a section to open it, or use a link in a row's **Ask Mo** card to jump to it.

| Section | One row per | Opens |
| - | - | - |
| **Handoffs per instruction** | Instruction the AI followed when it handed off. **AI profile instruction** quotes the rule from your AI profile. | The instruction, or your AI profile |
| **Prohibited topics** | Prohibited topic that matched. | Your prohibited topics in **Settings → Autopilot** |
| **Missing knowledge** | Knowledge article the AI found but that didn't answer the question. **No relevant knowledge found** collects handoffs where nothing matched. | Your knowledge sources |
| **Missing or insufficient tools** | Action the AI tried that didn't complete the request, marked with a warning icon. **Missing tool** collects handoffs where no action existed. | The action, or your actions list |

Each section shows its ten largest rows; the rest are summed as **+N more with fewer handoffs**. Expand a row to read the AI's explanation for each session, five at a time, with **See the session in inbox** to open the full session.

## Get a recommended plan

**Get expert help →**, at the top of the page, summarizes the period and suggests up to four next steps. A step is suggested when one of your four most frequent reasons crosses its share of handoffs:

| Reason | Suggested above | Step |
| - | - | - |
| User requested a human | 20% | **Configure handoff settings** |
| Missing or insufficient tools | 10% | **Add new tools** |
| The AI followed instructions | 15% | **Review instructions** |
| Prohibited topic | 5% | **Review prohibited topics** |
| Missing knowledge | 10% | **Add knowledge** |

With fewer than two suggestions, it also suggests reading the handed-off sessions in your inbox. For a routine to work through these fixes, see [Increase automation](https://docs.open.cx/resources/increase-automation.md).

The older **Handoffs analytics** page, with handoff totals and breakdowns by team and language, is not offered in the sidebar but still opens from the command menu as **Reports > Handoffs**.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| **No handoff data available** | The AI made no handoffs in the selected range, or the range is before January 10, 2025 | Widen the date range. |
| A section says **No handoffs due to … in this period.** | No handoff in the range gave that reason | Nothing to fix for that reason. |
| The totals differ from **Handed Off** on the Impact Dashboard | Handoff Insights counts AI handoffs by when they happened, in UTC days. The Impact Dashboard counts sessions by the day they were created, in its chosen time zone, without assist-mode sessions | Compare trends over the same range rather than exact totals. |

***

## Related Documentation

> [card] [Increase automation](https://docs.open.cx/resources/increase-automation.md)
>
> A routine for fixing handoffs

> [card] [Impact Dashboard](https://docs.open.cx/reports/impact-dashboard.md)
>
> Automation rate and session flow

> [card] [AI Instructions](https://docs.open.cx/ai-instructions/overview.md)
>
> Change handoff rules

> [card] [AI Actions](https://docs.open.cx/actions/introduction.md)
>
> Give the AI missing tools


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