AI Handoffs report
In the app: Reports → AI Handoffs
Needs the 'View Reports' permission.
Shows why the AI agent hands conversations to your team and what you can change so it does so less. The page is titled "AI Handoff Insights". A handoff, also called an escalation, is the AI passing a conversation to a person.
Period, filters and export
- "Start date" and "End date": the period, both days included. The page opens on the last 30 days. A period can be at most 366 days.
- Store filter: appears when you have more than one store. It can include or exclude several stores.
- "Channels": limits the report to conversations on the chosen channels.
- "Day", "Week", "Month": the size of the steps in "Handoff rate over time".
- "Refresh" reloads the totals and charts. It does not reload the handoff list; change the period, filters or list page to request that again.
- "Export CSV" downloads the handoffs of the period and filters as a CSV file. The file holds at most 5,000 handoffs, the most recent first. With more than that, the older ones are left out and the file does not say so; choose a shorter period to get them. The first lines of the file state the period in UTC and the timezone its times are written in.
A handoff counts in the period in which it happened. On this page the period and the steps of the chart are cut at midnight UTC, not in your organization's timezone, so the first and last day can be off by a few hours for you. The page says so when it matters. Times in the list are shown in your own timezone.
A teammate whose access is limited to certain stores only sees those stores' handoffs.
The report needs the 'View Reports' permission. Someone without it sees "Access required". That message also names the AI Config permission, but that permission alone does not load the figures.
If one part of the page fails to load, it shows its own error and the other parts keep their figures.
Handoff totals
- "Total handoffs": the number of handoffs in the period. A conversation that was handed over twice counts twice.
- "Handoff rate": handoffs divided by the conversations the AI worked on in the period. A conversation is in that total when the AI did anything on it in the period, whenever the ticket was created; it is counted once however often the AI ran. Conversations the AI was not allowed to handle are not in that total. Because a conversation handed over twice adds two handoffs and one conversation, the rate is handoffs per AI conversation and not strictly the share of conversations handed over. With no AI conversations it shows a dash.
- "Avoidable handoffs": handoffs other than those recorded as a tool asking for a person, three exhausted return re-checks, a failed refund payout, a legal threat or a message from an authority. These are the handoffs a better setup could prevent. It is an indication based on the trigger and the reason, not a judgement of each conversation.
- "Avg AI turns to handoff": the average number of times the AI ran on the conversation before it handed over, over the handoffs for which that number was recorded.
Handoff rate over time
The handoff rate per day, week or month: handoffs in that step divided by the conversations the AI worked on in that step. A step with no AI conversations is plotted as 0%.
Reason code breakdown
The reason the AI gave when it handed over, with the number of handoffs and its share. The reasons and their names are managed under AI → Handoff reasons. Handoffs without a recorded reason are shown as uncategorized.
Click a reason to show only its handoffs in the list at the bottom.
Trigger breakdown
What made the handoff happen, as opposed to the reason the AI gave. Examples: the AI hit its reply limit, the message matched a keyword you flagged, a tool asked for a person, the run failed, or a refund that was accepted was not paid out. Click a slice to filter the list.
Tool-failure attribution
Which tool the AI ran last before each handoff.
- "Preceding tool": the tool, or "(no tool called)".
- "Handoffs": the handoffs that followed that tool.
- "Succeeded" and "Failed": whether that last tool call worked.
- "Top error": the error seen most on the failed calls.
A tool that often fails right before a handoff is a likely cause of avoidable handoffs, for example a store connection that stopped working. Click a row to filter the list.
Reason × Category
A grid of handoff reasons against the categories the AI's categorizer gave the conversations. A darker cell holds more handoffs. Click a cell to see how many handoffs are in it, a suggested next step with how urgent it is, and up to 5 sample conversations to open. When Squid has no specific suggestion for a cell, it says so. Some suggestions link to a settings page that needs a permission of its own.
Time to handoff
"Time to handoff" counts handoffs by how long the AI was in charge: from the customer's first message, or the creation of the ticket when there is none, to the conversation’s currently recorded handoff time, or the individual handoff time if no current time is recorded. For a conversation handed over more than once, this can differ from the time shown in the list, which uses each individual handoff. The groups run from under a minute to more than 24 hours.
"AI turns before handoff" counts handoffs by the number of times the AI ran before handing over, with the average above the chart. When an older handoff has no recorded turn count, this chart and the list use the conversation’s current count. The top average uses only counts recorded on the handoffs themselves.
Handoffs
The handoffs of the period, 25 per page, with "Previous" and "Next".
- "When": the moment of the handoff.
- "Ticket": the ticket, with a link. A dash means the conversation was deleted.
- "Store", "Reason" and "Trigger".
- "Last tool": the tool that ran last before the handoff.
- "AI turns" and "Time→HO": the number of AI runs and the time until the handoff.
- "Suggestion": the suggested next step for this handoff.
A click in one of the breakdowns above filters this list; "Clear drill filter" removes it. That filter is applied to the page you are on, so check the other pages too.