> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Handoff reasons in the Data Export API and MCP

The AI Agent now records why it hands a conversation to a human agent. It records a `reason_code` from a fixed list of ten values, or `null` when it records no code. It also records a `reasoning` text when one is available.

The v2 Conversations endpoint of the Data Export API now returns a `handoffs` array on each conversation. Each entry is a handoff attempt with its `outcome_status`, `reason_code` and `reasoning`. The [`get_conversation`](/mcp/tools/get-conversation) MCP tool returns `reason_code` and `reasoning.text` on its handoff entries. The new `HANDOFFREASON` filter in [`get_available_filters`](/mcp/tools/get-available-filters) filters conversations by reason code.

Use the reason codes to find handoffs that you can reduce, such as a failing Tool or a gap in your Knowledge.

See [Handoff reasons](/docs/handoffs/handoff-management/handoff-reasons) for the list of codes, and the [Conversation object reference](/data-export-conversation-object) for the full schema.