Two conversation attributes, Fin AI Agent escalated reason and Fin AI Agent escalated by, give you a detailed breakdown of every Fin escalation. Both are available in Reporting and can be used as filters, groupings, and columns in custom reports.

Note: Both attributes are only populated for escalations — Procedure handoffs do not receive a value. If a conversation moves out of the escalated state, both attributes are cleared. Historical conversations are blank.

Attributes

Attribute name	Description
Fin AI Agent escalated reason	Shows why Fin escalated a conversation to a teammate. Takes one of 14 values: User requested — The customer explicitly asked for a human. User is frustrated — Fin detected customer frustration. Clicked a quick reply button — The customer used a quick-reply or "talk to a person" option from a workflow. Escalation rule applied — An Escalation Rule matched. Workspace guidance applied — Escalation Guidance mandated the escalation. Custom answer handoff — A custom answer routed the conversation to a team. Out of scope — The customer's query fell outside Fin's scope. Custom tool error — A custom tool inside a Procedure failed. Code condition error — A Procedure Code Condition step failed. System error — An internal system error caused an escalation. Usage limit reached — The Fin usage limit was hit for the workspace. Voice escalation — A phone/voice call escalated. All voice escalations are grouped under this single value. API escalation — An escalation was requested through the Fin API channel. Other — The conversation escalated for a reason not captured by the above values.
Fin AI Agent escalated by	Shows which entity triggered the escalation. The value is the name of the entity responsible — such as a Procedure, Task, Guidance rule, Escalation Rule, Custom Answer, or Data Connector. Additional values: More than one guidance — When more than one guidance rule contributed to the escalation. (blank) — When no specific entity is responsible.

How to use these attributes

Add either attribute to any custom report in Reporting as a filter, grouping, or column. This lets you slice escalation data by reason or by the specific entity that triggered it.

For example:

Group by Fin AI Agent escalated reason to see which escalation reasons are most common across your conversations.
Filter by Fin AI Agent escalated by to measure how often a specific Guidance rule or Escalation Rule is causing handoffs.
Combine both attributes in a single report to get the full picture — for example, which entity is responsible for the majority of Workspace guidance applied escalations.

FAQs

Why is a conversation's escalated reason blank?

Both attributes are only populated while a conversation is in the escalated state. If the conversation moves out of that state, both attributes are cleared. Historical conversations prior to the release of these attributes will also be blank — there's no backfill.

Do Procedure or Task handoffs appear in these attributes?

No. These attributes only reflect escalations. Procedure handoffs and Task handoffs do not receive a value.

Why do all voice escalations show the same reason?

All phone and voice call escalations are grouped under a single Voice escalation value, regardless of the specific reason the call was escalated.

What's the difference between escalated reason and escalated by?

Escalated reason tells you why the escalation happened (e.g., the customer asked for a human, an escalation rule fired). Escalated by tells you which entity triggered it (e.g., the name of the specific Guidance rule or Escalation Rule). Use them together for the most complete picture of your escalation drivers.

Where can I use these attributes?

Both attributes are available in Reporting and can be used as filters, groupings, and columns in custom reports alongside other conversation attributes.

Escalation reporting metrics & attributes