> ## 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 Quality surface

> Read per-carrier call quality — MOS, jitter, packet loss, RTT, and the VAQI score — compare carriers over a window, drill into the worst calls, and tell a collection problem apart from a quality problem.

# Voice Quality

**Voice → Quality** (`/voice/quality`) is the carrier-route health surface. It answers one question: is the media path between you, your carrier, and the far end delivering clean audio — and when it isn't, which route is responsible?

The page rolls up RTCP reports collected across the call path into per-day aggregates: one row per carrier per day, with average MOS, p95 jitter, packet loss, and RTT. Everything on the page derives from those aggregates plus a worst-calls list and a collection-status verdict, all served by four tenant-scoped endpoints you can also call directly (see [API parity](#api-parity)).

## Where to reach it

Two paths, one page:

* Open the sidebar's **Insights** entry to land on the Insights hub (`/insights`), then click the **Voice Quality** tile. It carries a **Cross-link** badge because the surface lives in the Voice tree rather than under `/insights/*` — the hover hint reads "Lives in another section of the dashboard."
* Go directly to **Voice → Quality** (`/voice/quality`). The route is bookmarkable, and its window and carrier filters live in the URL, so a shared link lands on the same view.

Do not confuse this page with **Voice → Voice Agent Quality** (`/voice/vaqi`). VAQI measures voice-agent session mechanics — turn latency, barge-in, TTFB — and is covered in [Read the Voice Agent Quality Index (VAQI)](/guides/voice-agent-quality-vaqi). Voice Quality measures the carrier route underneath both human and agent calls: MOS, jitter, and packet loss per SIP trunk. When callers report bad audio on AI-agent calls, read this page first and the VAQI page second; the reverse order sends you debugging prompts when the media path is at fault.

## What the KPI cards report

Four cards head the page, each computed across every carrier in the selected window:

* **Avg MOS** — the mean opinion score across all calls with a quality sample in the window, weighted by the number of MOS-bearing measurements. The card's subtitle reports the sample base it was averaged over — read it before trusting the average on a low-volume tenant. The card warns when the average drops below 3.5, the boundary where listeners start sounding dissatisfied.
* **p95 jitter** — the worst-case jitter across per-day carrier rollups, in milliseconds. Sustained jitter above \~30 ms strains the receiver's jitter buffer; a rising p95 is the earliest sign of congestion on one leg.
* **p95 packet loss** — the worst-case per-day packet-loss percentage. Loss above \~5% chops audibly; even a good MOS mean cannot hide a bad loss tail.
* **p95 RTT** — round-trip time across the path. A rising RTT with flat loss usually means a congested or re-routed hop, not dropped packets.

Below the cards, four charts split the same aggregates by shape: a **MOS distribution histogram** (calls per MOS bucket per carrier), a **jitter trend** (per-day p50 and p95), an **RTT trend**, and a **packet-loss heatmap** (carrier rows × day columns, colored from green at ≤0.5% loss to red above 3%). Read the histogram's carrier stack before blaming "the network": one carrier owning the ≤3.0 bins while another sits at ≥4.0 points at a route, not your platform.

## Reading the carriers comparison

The page compares carriers four ways, all over the same window:

* The **heatmap** gives one row per carrier. A degrading route shows as a row warming (green → amber/red) over consecutive days — a degrading endpoint shows as one red cell in an otherwise green row.
* The **MOS histogram** stacks bars per carrier. Look for the carrier whose mass sits in the low bins; that is where your complaints come from.
* The **filter dropdown** narrows every card, chart, and the worst-calls table to one carrier, so you can re-read the whole page per route instead of mentally masking the stack.
* The **per-carrier anomaly cards** flag a carrier whose MOS broke with its own recent pattern. Each card's **Investigate** action applies that carrier as the filter and keeps your current window — use it instead of re-ticking filters by hand.

A degrading route and a degrading endpoint look alike in a one-day snapshot. The distinguishing read: if the heatmap row worsens across days while other carriers on the same trunks stay flat, the route is degrading; if all carriers worsen on the same day, look at your own network first.

## Drilling into worst calls

The **Top 10 Worst Calls** table lists the lowest-MOS calls in the active window, lowest first. Each row carries the call's measured set: carrier, negotiated codec, MOS, average jitter, packet loss, and the time the sample was recorded, rendered in your timezone.

MOS badges tier the value so color is never the only cue: **Good** at 4.0 and above, **Fair** between 3.5 and 4.0, **Poor** below 3.5. A dash means the call has no quality sample yet — common on calls that completed without an RTCP report arriving.

Click a row to open the same call detail sheet the Voice → Calls list uses, with the full call record, audio, and transcript when present. The jump keeps you in context: table → call → back, without re-navigating. When an empty table claims "no low-MOS calls," check it is the congratulatory empty state and not the load-error state — the page renders an explicit error row when the worst-calls endpoint is unreachable instead of claiming a clean window.

## The collection-status pill

The header carries an always-visible pill beside the page title that reports whether quality monitoring itself is working, regardless of whether the charts have data. It answers the question operators otherwise guess at when a window looks empty: is the pipeline off, or was the window genuinely quiet?

* **Monitoring off** — collection is not configured, so no sample can ever land. The empty charts are a setup problem, not a quality verdict.
* **No recent data** — collection is configured but no quality-bearing sample arrived in the lookback window. Either traffic was genuinely absent from the measured path or a webhook is not reaching the collector.
* **Monitoring active** — samples are landing; what the charts show is real.

When the verdict is off or no-recent-data, admin seats see an enable action beside the pill. The pill disappears only during a transient metrics outage, where the retry banner owns the explanation — it never contradicts an outage with a false "monitoring off" verdict.

## Window, carrier filter, and shareable links

The **Date range** control offers 7d, 30d, and 90d windows (7d default). Read 7d for incident triage, 30d for a weekly operations pass, and 90d for baselining before you compare carriers — one bad afternoon should not move a 90d mean.

Both the window and the carrier selection live in the URL (`?days=30&carrier=<name>`), so a deep link reproduces the exact view. The anomaly cards preserve the window when they route into a carrier, and the page auto-refreshes every 60 seconds — safe to keep open during a change window.

## API parity

Everything the page renders comes from four tenant-scoped endpoints; the dashboard is a thin client over the same reads:

```bash theme={null}
# Per-period rollup per active SIP trunk: avg MOS, p95 jitter, packet loss, VAQI score
curl "https://api.orbit.devotel.io/api/v1/voice/quality/aggregates" \
  -H "X-API-Key: $ORBIT_API_KEY"

# Distinct carriers seen in the last 30 days
curl "https://api.orbit.devotel.io/api/v1/voice/quality/carriers" \
  -H "X-API-Key: $ORBIT_API_KEY"

# Lowest-MOS calls in the window (the worst-calls table)
curl "https://api.orbit.devotel.io/api/v1/voice/quality/worst-calls?limit=10" \
  -H "X-API-Key: $ORBIT_API_KEY"

# Is quality collection configured, and have recent samples landed?
curl "https://api.orbit.devotel.io/api/v1/voice/quality/collection-status" \
  -H "X-API-Key: $ORBIT_API_KEY"
```

The aggregates and worst-calls endpoints accept the same window the dashboard uses (`?days=` as the preset, or `from`/`to` ISO dates), and `carrier=` narrows the aggregates the way the dashboard filter does. The **VAQI score** in the aggregates response is the 0–100 rollup derived from MOS, jitter, packet loss, and one-way-audio detection — one number to guard in an external monitor when the dashboard's four cards are too many. Per-call field and endpoint details live in the [Voice API reference](/api-reference/voice).

## Troubleshooting

Match the symptom pair before you treat the page as a verdict:

* **Low MOS with near-zero packet loss** — codec negotiation, not the network. Check the worst-calls table's **Codec** column against what your trunk offers.
* **Packet loss with good MOS on other carriers** — network congestion on the flagged route, not your platform. The carrier comparison above isolates it.
* **One-way audio** — the aggregates VAQI score counts one-way-audio detection as a quality deduction; a dropped VAQI with clean MOS/jitter/loss points at it specifically.
* **All charts empty with calls flowing** — read the collection-status pill first. "Monitoring off" or "No recent data" is a setup problem, not a clean bill of health.
* **Averages look fine but callers complain** — read p95, not the mean; the warn highlight fires on p95 exactly because averages hide the tail.

For the full symptom-family playbook — dead air, choppy audio, codec mismatches, and how to capture per-call evidence before opening a ticket — see [Voice call quality troubleshooting](/troubleshooting/voice-call-quality).

## See also

* [Read the Voice Agent Quality Index (VAQI)](/guides/voice-agent-quality-vaqi) — the session-mechanics complement: turn latency and barge-in per voice-agent session
* [Voice call quality troubleshooting](/troubleshooting/voice-call-quality) — symptom families and escalation evidence
* [Insights hub orientation](/insights/overview) — where the Voice Quality tile sits among the analytics surfaces
* [First outbound voice call](/guides/first-outbound-voice-call) — get a trunk live before reading its quality