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

# Read the Voice Agent Quality Index (VAQI)

> Read per-session voice-agent quality — latency percentiles, turn-taking, and barge-in events — pick the right window, set acceptable thresholds per use case, wire regressions into KPI alerts, and diagnose a latency regression end to end.

# Voice Agent Quality Index (VAQI)

Reading [Voice → Intelligence](/guides/voice-intelligence-trends) tells you what callers said and how it felt. **Voice → Voice Agent Quality (VAQI)** answers the mechanical question underneath: is the line answering fast, and does the conversation flow cleanly, per voice-agent session?

Open it at **Voice → Voice Agent Quality** with the console route `/voice/vaqi`. The page reads per-session records the voice gateway records at the end of each session and rolls them up into percentiles and averages over a configurable day window. Cards auto-refresh every 30 seconds, so you can keep the page open during a change window.

## What VAQI measures

VAQI computes each metric across all completed voice-agent sessions in the window, so every value has the same denominator. The **Sessions** headline card tells you how many sessions fed the rollup — check it before trusting any average below it.

### Latency percentiles

* **TTFB (time to first byte)** — per session, the average time from the end of a caller's turn to the first audio byte the agent speaks. The card shows the mean across sessions and the p95 across per-session averages, so one bad session cannot hide inside the mean. Callers read a pause over roughly a second as a dead line; a rising p95 is the earliest sign of an LLM or STT slowdown.
* **Turn gap** — the average silence between turns within a session (the per-turn counterpart of TTFB). Again mean plus p95. The dashboard highlights the card when p95 exceeds 1500 ms (TTFB warn threshold is 1200 ms).

Below the two latency cards, three component cards split where the time goes: **average STT latency**, **average LLM latency**, and **average TTS latency**. A regression reads differently depending on which component moved — LLM time usually means a model or prompt change, STT time points at speech recognition, and TTS time at the speech synthesis path.

### Turn-taking and barge-in events

* **Turns per session** — the average number of caller↔agent exchanges. Longer sessions with healthy turn counts mean the agent is actually conversing; a drop can mean the agent hangs up early or callers abandon.
* **Barge-in rate** — the share of turns where the caller interrupted the agent's speech. Some barge-in is healthy — callers who cannot interrupt experience the agent as a talking wall. A rising rate after a prompt change usually means the agent is too verbose or answers without pausing.
* **Barge-in success rate (clean yield)** — of all interruptions, the share where the agent stopped cleanly and let the caller take the turn. A low success rate means the agent talks over interruptions and produces the double-speak overlap that callers describe as "the bot wouldn't let me speak."

Together these three metrics separate two failure modes that look identical from the CSAT side: callers complaining "the bot never listens" (high barge-in, low yield) versus "the bot takes forever" (turn-gap or TTFB regression).

## Where to find it and how to pick the time window

The page lives under **Voice → Voice Agent Quality** (`/voice/vaqi`) — not under Insights. Insights aggregates content (sentiment, topics); VAQI measures session mechanics.

The window selector in the header offers **24h**, **7d** (default), and **30d**. The choice lives in the page URL as `?days=`, so you can bookmark or share a link that lands on a specific window. Use **24h** for incident triage ("is the regression still moving?"), **7d** for a weekly operations read, and **30d** for baselining before you set thresholds — one bad afternoon should not move a 30d mean.

## Reading the breakdown and setting thresholds

The **Daily breakdown** table lists one row per day: session count, average turn gap, and average TTFB. Two reads matter:

* **Sample size first.** A day with 3 sessions averaging 900 ms is noise; a day with 400 sessions averaging 900 ms is a regression. The table gives you the per-day denominator.
* **Compare like-for-like weekdays.** A Monday that lands above the previous Monday's turn gap is a signal; a Monday above a Saturday is traffic-mix, not a problem.

The dashboard defines its own warn thresholds (p95 TTFB 1200 ms, p95 turn gap 1500 ms), but what is acceptable depends on your use case. Tune your own thresholds against a 30d baseline:

| Use case                                | p95 TTFB   | p95 turn gap | Barge-in rate              | Barge-in success |
| --------------------------------------- | ---------- | ------------ | -------------------------- | ---------------- |
| Support voice bot (FAQ/self-serve)      | \< 1200 ms | \< 1500 ms   | 5–20% is normal            | > 80%            |
| IVR-assist (menu navigation)            | \< 900 ms  | \< 1200 ms   | low expected               | > 90%            |
| Outbound agent                          | \< 1200 ms | \< 1500 ms   | tolerable if short calls   | > 70%            |
| Inbound, long-form (e.g. claims intake) | \< 1500 ms | \< 2000 ms   | high means verbose prompts | > 80%            |

Set the threshold on **p95**, not the average — averages hide the tail that callers remember. Revisit thresholds after a model swap or prompt rewrite, and record them somewhere your ops team owns (they are tenant-owned configuration; nothing on this page changes routing or carriers).

## Wire a VAQI regression into KPI alerts

The dashboard tells you quality moved; an alert tells you without anyone opening the page. Create a rule in **Insights → Alerts** against the KPI that proxies session quality — most teams guard **AI containment** (a latency regression that makes callers hang up shows as a containment drop) or **CSAT** on the survey surface:

1. Open **Insights → Alerts** (`/insights/alerts`) and click **Create rule**.
2. Pick the metric (containment for mechanical regressions, CSAT for caller-felt quality).
3. For a known number, use a **threshold** rule — e.g. containment below 70% over a 7d window. If you do not know the right number yet, use **anomaly** mode, which flags a drop against the metric's own learned baseline.
4. The fired notification deep-links into the metric page; from there, VAQI tells you whether the root cause is mechanical (latency, turn-taking) or content (prompt, routing).

Endpoint and field details are in [KPI alerts on business metrics](/guides/kpi-alerts). Usage and delivery anomaly rules cover the transport side; KPI alerts cover the experience side — use both.

## Worked example: a latency regression after a model swap

A tenant swaps the LLM model behind their support voice bot on a Monday to cut token cost. By Wednesday, CSAT on the post-call survey is sliding. The team reads the VAQI page with a 7d window:

1. **Sessions** card shows \~1,900 sessions in the window — the aggregates are trustworthy.
2. **TTFB** card reads `890 ms avg / 1.9 s p95`, highlighted above the 1200 ms warn threshold. Previously it sat at `620 ms / 1.1 s`.
3. The component cards isolate it: **avg LLM latency** moved from 410 ms to 780 ms, while STT and TTS stayed flat. The cheaper model is slower to first token.
4. The **daily breakdown** confirms the anchor: turn gap climbs starting Monday, matching the deployment — a step change, not gradual drift.
5. **Barge-in rate** ticked up from 12% to 19% — callers started interrupting the slower-speaking agent — while **barge-in success** held at 91%, so at least interruptions yield cleanly.
6. The fix decision is now a trade-off with numbers on both sides: keep the cheaper model and accept \~1.9 s p95 (below the 2 s threshold the team set for this use case), or revert to the faster model and treat the delta as the price of the upgrade path. A threshold alert on containment catches the caller-visible effect if the team keeps the swap.

The dashboard reclaimed the diagnosis in one read: without the component split, the same CSAT slide would have sent the team into prompt debugging.

## Analytics API and permissions

The page is a thin client over one tenant-scoped endpoint:

```bash theme={null}
curl -H "x-api-key: $ORBIT_API_KEY" \
  "https://orbit.devotel.io/api/v1/voice/vaqi?days=7"
```

`days` accepts 1–30 and defaults to 7. The response is the standard envelope with the rollup the cards render:

```json theme={null}
{
  "data": {
    "days": 7,
    "sessions": 1923,
    "avg_session_duration_ms": 132000,
    "avg_turns_per_session": 8.4,
    "avg_turn_gap_ms": 640,
    "p95_turn_gap_ms": 1180,
    "avg_ttfb_ms": 620,
    "p95_ttfb_ms": 1090,
    "avg_stt_ms": 180,
    "avg_llm_ms": 410,
    "avg_tts_ms": 220,
    "barge_in_rate": 12.4,
    "barge_in_success_rate": 90.8,
    "daily": [
      { "date": "2026-08-27", "sessions": 288, "avg_turn_gap_ms": 610, "avg_ttfb_ms": 590 }
    ]
  }
}
```

Per-session records carry a per-agent identifier; when the tenant runs several voice agents, poll with a short window during a regression to isolate the offending deployment before drilling into session detail.

* **Dashboard route** — restricted to **owner, admin, and developer** roles, the same gate as the rest of voice settings and quality signals. Other roles see no page.
* **API** — a valid API key or JWT on the voice reads surface. Rate-limited like the other voice read endpoints.
* **Alert rules** — reads need the analytics read scope; creating, updating, or deleting a rule additionally requires owner, admin, or developer, and each change is recorded in the audit log.

## Troubleshooting

* **"No voice AI sessions yet for this period."** No completed voice-agent sessions fall in the selected window. Widen to 30d; metrics appear as soon as the voice gateway completes a session.
* **Page fails to load.** The page surfaces the error with a retry action rather than an infinite spinner, and sessions keep recording — it is a dashboard-only outage. If it persists, check [status.orbit.devotel.io](https://status.orbit.devotel.io).
* **Averages look fine but callers complain.** Read p95, not the mean; the warn highlight fires on p95 exactly because averages hide the tail.

## See also

* [Read the Voice → Intelligence page](/guides/voice-intelligence-trends) — the content counterpart: what callers said, not how fast the line answered
* [KPI alerts on business metrics](/guides/kpi-alerts) — threshold and anomaly rules for containment, CSAT, and LLM spend