Skip to main content

​
Mine deflection gaps into knowledge base additions

Every time a customer asks your AI something it cannot answer — because the knowledge base has no candidate article, or because the best candidate’s match confidence lands below the threshold — Orbit records the question as a deflection miss. The Deflection Gaps page groups those misses into clusters so you see “46 contacts asked about refund timing — your KB has no article” instead of 46 separate log lines, then hands you a guided chip to draft the missing article directly from the cluster. This guide covers Agents → Knowledge base → Gaps in the dashboard (/agents/knowledge-base/gaps) and the two API endpoints behind it. It closes the loop that Auto-draft help articles from resolved conversations starts: auto-draft mines conversations your AI resolved; the gap miner surfaces the questions it missed.

​
Where the gap panel fits

Open Agents → Knowledge base, then choose the Gaps view. The page header shows the total miss count for the current window and the number of clusters, with two controls:
  • Look-back window — 7 to 90 days (default 30). Everything below is computed inside this window.
  • Cluster count — how many clustered misses to list (default top 10).
Each cluster row shows the representative customer question, the miss count (the raw number of recorded misses in the cluster), the distinct conversation count, a suggested topic chip, and the most recent customer questions verbatim. A cluster is the unit of work: you promote the whole cluster into one draft article, not one question at a time. The same data is available over the API:
The response is a report { days, total_misses, clusters } where each cluster carries cluster_id, representative_query, miss_count, conversation_count, suggested_topic, and up to three recent_examples. total_misses is the true miss count for the window — it is not capped by the clustering sample, so use it for the badge number, not the cluster sum.

​
What counts as a miss — the two signals

A miss is recorded the moment the deflection ranker fails a customer’s question, in one of two shapes:
  1. No candidate — the ranker found nothing in the attached knowledge base that could answer the question. The KB lacks the topic entirely.
  2. Low confidence — a candidate article existed but the match confidence came in below the publish threshold, so the customer was escalated instead of answered. Topic-adjacent material exists, but it does not actually resolve the question.
Both shapes tell a KB author the same thing — write an article here — but the first is a coverage gap and the second is a resolution-quality gap. The Deflection Gaps page deliberately shows the union. A companion signal lives on the knowledge-base-scoped endpoint GET /api/v1/agents/knowledge-bases/:id/gaps: that one derives gaps from assistant turns that contained “I don’t have that information”-class phrasing, or from conversations escalated to a human. The deflection-miss report above is captured synchronously at the moment of failure; the per-knowledge-base report catches the same failures from the agent conversation side. Check both when a cluster seems thin — the gap you are looking for may be filed under the other signal.

​
How clustering works

Misses are grouped by token overlap: each question is tokenized (stopwords and punctuation stripped), and two questions join the same cluster when their token sets overlap at a Jaccard similarity of 0.4 or higher. Clusters sort by miss count, with the conversation count breaking ties, so the highest-impact gap sits on top. Every cluster carries a suggested topic — the highest-frequency meaningful token across the cluster’s questions. It is not the article title; it is the starting hint for the article’s slug. A cluster whose top token is refund is telling you where to file the article, not what to name it. The cluster_id on each cluster is a stable hash of the cluster’s tokens. Re-running the same window over the same data yields the same id, which is what lets the promote endpoint (below) re-derive the cluster from the id alone. It also means the id is only valid inside the window you listed — change days, and the same cluster carries a different id.

​
Promote a cluster into a draft article

In the dashboard, pick the knowledge base the new article should land in from the header dropdown, then click Create draft article on a cluster. Orbit drafts an answer card from the cluster’s real customer questions — the title seeded by the suggested topic, the body built from what customers actually asked — and uploads it into the selected knowledge base as a draft document. You are then deep-linked into that knowledge base to review it. Over the API:
  • knowledge_base_id (required) — the target knowledge base. Promote never creates a knowledge base for you; which base a gap belongs to is a content organization decision only you can make. If the workspace has no knowledge base yet, create one first.
  • title_hint (optional) — nudges the drafted title toward the angle you already have in mind. The suggested topic chip is the dashboard’s seed for this field.
  • days (optional, default 30) — must match the window you listed the cluster under. The endpoint re-runs the clustering pass and looks the cluster up by id, so a days mismatch (or a window so old the cluster aged out) returns a 404 that says the cluster was not found in the selected window.
The response echoes the new document_id, the draft title, and the source_cluster it came from. Promoting is a write action — it requires an owner, admin, or developer role, same as editing knowledge base content.

​
Review and publish

The promoted cluster lands as a draft — the same pending-review state the auto-draft pipeline uses. A draft never grounds a live AI answer: its content is not embedded and not retrievable until a human approves it. Review the draft in Agents → Knowledge base:
  1. Open the draft document. The body lists the verbatim customer questions from the cluster — treat it as raw material, not a finished article.
  2. Rewrite the body into the answer customers should receive, filling in the facts the drafter could not know (policies, windows, prices).
  3. Approve the document. Approval embeds its chunks, making the article retrievable by every agent attached to that knowledge base — the next customer who asks the clustered question gets the answer instead of an escalation.
  4. Or reject it when the cluster was noise.
The same lifecycle is available over the API — POST /knowledge-bases/:id/documents/:docId/approve and POST /knowledge-bases/:id/documents/:docId/reject. The full document lifecycle is in Build and Maintain an AI Knowledge Base.

​
The two mining loops work together

The Deflection Gaps page and the auto-draft pipeline cover opposite halves of the same loop:
  • Auto-draft mines resolved conversations and drafts articles for recurring reasons the analysis flags as best covered by a help article.
  • Deflection gaps capture the questions that were not resolved — the ranker missed and the customer escalated — and let you promote those clusters into drafts.
Both pipelines land drafts in a knowledge base behind the same human review gate, and both respects per-topic dedup through your review decisions. Running both is the intended steady state: auto-draft fills the articles for what your AI handles, gap-mining fills the articles for what it misses. See Auto-draft help articles from resolved conversations for the auto-draft configuration.

​
Diagnostics — when clusters or suggestions stop appearing

The page is empty but customers are escalating. The window may be too short — widen the look-back dropdown. If it is still empty, no deflection misses were recorded in the window at all: either the knowledge base really is covering everything, or no agents ran deflection in the period. Check the companion per-knowledge-base report (GET /agents/knowledge-bases/:id/gaps) which picks up the same failures from the assistant-turn side. A promote returns 404 with “cluster not found”. The cluster id only resolves inside the window it was listed under. Re-list the gaps with the same days value, take the current cluster_id, and promote that. A cluster also ages out naturally — once its misses fall outside the window, the id no longer resolves. This is by design: the drafts always build from recent questions, not stale ones. The same cluster reappears after you promoted it. Promoting files a draft but does not delete the underlying misses — they stay in the window until they age out. If you do not want to see the cluster again, approve or reject the draft: the published article starts absorbing the traffic, and the rejected draft marks the topic as reviewed. Miss counts look stuck at the window cap. The clustering pass samples the most recent misses in the window and the cluster list is intentionally bounded; total_misses keeps the true count. Raise limit (up to 50 clusters) to see more clusters, or shorten the window to re-rank.

​
See also