Skip to main content

​
Number health diagnostics console walkthrough

When a DID stops delivering, the first signal is not a carrier notice — it is a drift in the health counters the daily scheduler already collects. The per-number health surface surfaces that drift before it becomes a blocked campaign: a delivery-rate drop, a complaint-rate tick up, a DLR-miss spike, or an abnormal trunk counter that says the upstream route is degrading, not the number itself. This guide covers the Numbers → [select a number] → Health surface in the dashboard: what each metric means, how the score-tier bands map to decisions, how to tell a number problem from a trunk problem, and when to swap, wait, or reroute. For the API that backs this surface, see Number health, warming, and carrier reputation tracking; for trunk-level diagnostics, see SIP trunk health and connectivity diagnostics.

​
Where the health surface lives

Open Numbers in the dashboard, select a DID from the list, and open the Health tab. The surface has two panels:
  1. Reputation score — a 30-day rolling deliverability score with a tier badge (Excellent / Good / Fair / Poor / Critical / Unknown), the breakdown rates (delivery, failure, complaint), the minimum sample-size threshold, and the last-computed timestamp.
  2. Health trend & forecast — a time-series panel that plots the score over a configurable window (30, 60, or 90 days) and projects it forward. It also flags step-change anomalies — a score dropping 12+ points between two ticks — which a slow slope would smear away.
Both panels read from the same data source: the daily health-score scheduler that persists per-number aggregate counters. No live carrier call runs when you open the tab; every metric is a locally-stored snapshot refreshed on a daily cadence. For the fleet-wide view — which numbers across your entire inventory need attention first — use the reputation-alerts banner on the Numbers dashboard, fed by GET /api/v1/numbers/reputation-alerts. The per-number Health tab is the drill-down that tells you why a flagged number landed on that banner.

​
What health telemetry is gathered per DID

The daily scheduler computes five counters for every number that has sent outbound traffic in the rolling 30-day window: The scheduler folds these counters into a composite health score (0–100) and assigns a tier: excellent (85+), good (70–84), fair (50–69), poor (30–49), or critical (under 30). Numbers under the minimum sample-size threshold return tier: "unknown" with no numeric score — there is not enough history to give a reliable signal.

​
How to read a degraded signal and decide swap vs wait vs reroute

When a number’s tier drops to poor or critical, you have three choices. The right one depends on what the breakdown tells you.

​
Decision tree

  1. Check the breakdown. Open the Health tab and look at the three rate columns — delivery, failure, complaint. Which one moved?
  2. Cross-reference the trunk. Open Voice → SIP trunks → [the trunk this number rides on] → Health and compare. Are the trunk’s peers also degraded?
  3. Decide.

​
When to wait and re-check

The daily scheduler runs once per 24-hour cycle. A single bad tick is not a trend. Wait and re-check when:
  • The DLR-miss rate spiked on one tick but the delivery and complaint rates are unchanged.
  • The failure rate moved by less than 5 percentage points and the number is still in fair or better.
  • The trend line shows stable (movement under 0.2 points/day) even though the current score is lower than you would like.

​
When to reroute (trunk-level, not number-level)

Reroute means keeping the number but pointing it at a different termination trunk — a carrier-level change, not a number replacement. Do this when the trunk-abnormal counters spike across every number riding that trunk. The SIP trunk diagnostics page (Voice → SIP trunks → Health) tells you whether the trunk itself is degraded; when it is, rotating the number does nothing — the next number on the same trunk hits the same failing upstream. Reroute first, then re-check the number health after the new trunk settles.

​
Number intelligence vs voice SIP trunk diagnostics: which page for which signal

Operators commonly confuse a per-number health signal with a trunk health signal because both surfaces show delivery and failure metrics. The table below disambiguates them. The rule of thumb: if the Health tab on the SIP trunk page shows green but the number Health tab shows red, the problem is the number. If both are red, the problem is the trunk — fix the trunk first, then re-evaluate the number.

​
Worked examples

​
Troubleshooting a degraded US 10DLC DID

A US 10DLC number (+1 415 555 0100) shows tier: "poor" with a complaint rate of 1.8 % and a delivery rate of 82 %. The failure rate is 6 % and stable.
  1. Open the number’s Health tab. The complaint rate is above the 1 % threshold.
  2. Open the SIP trunk Health tab for the trunk this number rides on. The trunk is registered with every probe step ok, and peer numbers on the same trunk show good or excellent tiers with complaint rates under 0.5 %.
  3. Decision: swap. The number has drawn a carrier flag. Quarantine the number, order or select a warmed replacement from the same 10DLC campaign, migrate the dialer campaign and sender pools to the replacement, and retire the original. If you configured the closed-loop reputation remediation policy under Settings → Numbers → Reputation, this sequence runs automatically on the next daily tick.

​
Cross-SIP compare vs the SIP trunk diagnostics guide

A number shows tier: "critical" with a failure rate of 45 %. You suspect a trunk problem but are not sure.
  1. Check the trunk Health tab: the trunk is unregistered with the register step pending. The SIP trunk diagnostics page tells you this is a NAT pinhole — the registrar did not answer the REGISTER within the probe budget.
  2. Check peer numbers on the same trunk: every one shows tier: "critical" or "poor" with the same failure-rate spike.
  3. Decision: reroute. The trunk is not reachable, so every number on it is failing. Switch the trunk’s transport from udp to tcp (as the SIP trunk diagnostics guide recommends for NAT pinholes), or reroute traffic to a different trunk. Do not swap any individual number — the numbers are fine; the trunk is not.
  4. After the trunk recovers, re-check the number Health tab. If the failure rate drops back to normal within one tick, no number action is needed.

​
API surface

The Health tab reads from two endpoints under GET /api/v1/numbers:
  • GET /api/v1/numbers/:id/health — the point-in-time health snapshot. Returns score, tier, breakdown (delivery / failure / complaint rates), min_sample_size, and last_computed_at. When the sample is too small, score is null and tier is unknown.
  • GET /api/v1/numbers/:id/health/trend — the time-series panel. Accepts window (30d / 60d / 90d), bucket (day / week), and horizon_days (1–60). Returns the per-period score array, the direction (improving / declining / stable), the forecast (projected score and tier), and any anomaly detection.
Both endpoints are pure reads of locally-persisted daily snapshots — no live carrier call, no outbound voice or SMS path. For the full endpoint catalog — warming, reputation, spam-likelihood, branded-calling analytics, and the closed-loop remediation policy — see Number health, warming, and carrier reputation tracking.

​
Tenant scope

Every metric on the Health tab is scoped to your own numbers and your own outbound traffic. The daily scheduler computes counters from your tenant’s message and call records; a number you do not own returns 404, and a wrong number ID from another tenant is indistinguishable from a wrong ID in your own tenant — ownership is never leaked across tenants.

​
See also