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

# Close knowledge-base deflection gaps

> Read the Deflection Gaps page — the clustered list of customer questions the AI deflection ranker missed — and turn each cluster into a reviewed, published KB article.

# Close knowledge-base deflection gaps

Every customer question your AI deflection ranker cannot answer — because
the knowledge base has no candidate article, or because the best candidate's
confidence falls below the answer threshold — is recorded the moment the
miss happens. The **Deflection Gaps** page turns those misses into a
clustered report: "47 contacts asked about refund timing — your KB has no
article," with a suggested topic and the verbatim questions behind each
cluster.

Open it at **Agents → Knowledge base → Gaps** (`/agents/knowledge-base/gaps`).
The page exists so KB authors work from a ranked queue of what the AI
missed, not from individual escalations.

You can also read the same report over the API:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/inbox/knowledge-gaps?days=30&limit=10" \
  -H "X-API-Key: dv_live_sk_..."
```

The response is a report `{ days, total_misses, clusters }` where each
cluster carries `cluster_id`, `representative_query`, `miss_count`,
`conversation_count`, `suggested_topic`, and recent `examples` of the
verbatim customer questions.

## What the deflection-gap list captures

A miss is recorded at the exact moment the ranker fails an incoming
question, in one of two shapes:

1. **No candidate** — the ranker searched the attached knowledge base and
   found nothing that could answer the question. The topic is missing
   entirely.
2. **Below the deflection threshold** — a candidate existed, but its match
   confidence came in under the 0.75 deflection threshold, so the customer
   was escalated instead of answered. Topic-adjacent material exists, but
   it does not actually resolve the question.

Both shapes tell you the same thing — *write an article here* — but the
first is a coverage gap and the second is a resolution-quality gap. The
page shows the union on purpose: a low-confidence match and a complete
absence both end in the same customer experience, an unanswered question.

Only genuine attempts count. When deflection never ran on a conversation —
no AI key configured, or an empty inbound message — nothing is recorded,
so the report is not diluted with unattempted deflections.

## 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 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.

Each cluster row shows:

* **Miss count** — how many times this question cluster was missed in the
  window.
* **Conversation count** — how many distinct conversations produced those
  misses, so you can tell one persistent customer asking ten times apart
  from ten customers asking once.
* **Suggested topic chip** — 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.
* **Recent examples** — the most recent customer questions, verbatim, so
  you write to what customers actually ask rather than a paraphrase.

The page header totals the misses for the current window even when the
cluster list is sampled short, so the badge number is the true count, not
the visible list size. Two controls adjust the report: the **look-back
window** (7 to 90 days, default 30) and the **cluster count** (top 5 to 50,
default 10).

## Two gap signals, side by side

The parent **Knowledge base** page already carries an older knowledge-gap
report. They answer different questions:

* **The Knowledge base page panel** keys on the agent-conversation signal:
  assistant turns that contained "I don't have that information"-class
  phrasing, and conversations escalated to a human citing a knowledge gap.
  It derives gaps after the fact, from what agents said.
* **The Deflection Gaps page** (this guide) keys on the deflection-miss
  signal: the customer's question captured synchronously the moment the
  ranker could not answer it.

The two are siblings, designed to be merged into a single tab later; today
they live side by side. Use the deflection-miss list when you want the
questions customers brought to the AI; use the older panel when you want
the failures your agents admitted to. A topic that shows up in both is
your highest-confidence gap.

## Workflow — turn a cluster into a published article

1. **Pick a cluster.** Start at the top of the list — it is already sorted
   by miss count. Open the recent examples to confirm the questions really
   share an answer.
2. **Choose the target knowledge base.** The header dropdown lists your
   knowledge bases; drafts land in the one you select. The dropdown's state
   is explicit — loading, load-failed (with retry), and genuinely-empty are
   three different messages — and the draft button stays disabled until a
   base is chosen.
3. **Create the draft article.** 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.
4. **Review and publish.** A draft never grounds a live AI answer. Rewrite
   the body into the answer customers should receive, fill in the facts the
   drafter could not know (policies, windows, prices), then approve the
   document. Approval makes it retrievable by every agent attached to the
   base — the next customer who asks gets the answer instead of an
   escalation.

Over the API, the same step is one call:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/inbox/knowledge-gaps/9f4c1a2b3d4e5f60/promote" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_id": "kb_0123456789abcdef0123456789abcdef",
    "title_hint": "Refund timing after cancellation",
    "days": 30
  }'
```

The `cluster_id` is a stable hash of the cluster's tokens — re-running the
same window over the same data yields the same id. It is only valid inside
the window you listed: change `days`, and the same cluster carries a
different id. A `days` mismatch (or a window so old the cluster aged out)
returns a 404 saying the cluster was not found in the selected window —
re-list with the same `days` value and use the fresh id. `days` defaults
to 30 when omitted.

Promoting is a write action — it requires an owner, admin, or developer
role, same as editing knowledge base content — and it 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.

## When the queue is empty

An empty list is one of two states, and the page text distinguishes them:

* **Complete coverage** — misses arrived and the knowledge base answered
  every one. This is the goal state; nothing to do.
* **No deflection traffic yet** — no agent ran deflection in the window.
  Widen the look-back dropdown first; if the list is still empty, attach a
  knowledge base to an agent and let inbound traffic flow. Misses start
  accumulating the first time a real question fails to match.

While the queue is empty, the sibling panel on the Knowledge base page
still works — the agent-conversation signal picks up low-confidence
assistant turns and escalations even when no deflection attempt was
recorded — so a brand-new workspace can start mining gaps before the first
deflection miss lands. Check the other signal when a cluster here seems
thin; the gap you are looking for may be filed there.

## See also

* [Mine deflection gaps into knowledge base additions](/guides/knowledge-gap-miner) — the agent-conversation-signal route to gap mining, and the auto-draft counterpart
* [Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle) — the review and publish lifecycle for drafts
* [Attach knowledge bases to agents](/guides/agent-grounding-citations) — get deflection traffic flowing onto the queue


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