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

# BanSafe Health

> Read a present account Health estimate, its source, fresh-evidence coverage, explanation, and observed account state.

BanSafe Health estimates the present state of eligible production Linked Device
sessions on a 0–100 scale. Test numbers, Cloud API sessions, and simulated
sessions do not receive an estimate. Higher is healthier. Each estimate
describes the account at its recorded evaluation time.

The launch estimator is `rules_v1`. It applies versioned rules to fresh
operational measurements and reports the deductions behind the score. A learned
estimator remains on the roadmap while Polymorfa collects production
measurements and trusted account-state labels.

Open **Safety** in Console, or call `GET /platform/bansafe/health` and
`GET /platform/bansafe/health/{session}` with a `sessions:read` credential.

Collection freshness and the source measurements have their own read surface.
See [Telemetry and collection](/guides/bansafe/telemetry).

## What the response means

A valid estimate includes:

* `health`, from 0 to 100;
* `band`, derived from that estimate;
* `healthEstimatorVersion` and `healthEvaluatedAt`;
* `healthFeatureCoverage`, from 0 to 1;
* `healthSource: "rules_v1"` and `healthReliability: "rules_based"`; and
* `healthExplanation`, with bounded deductions and the evidence groups that
  were measured or missing.

For `rules_v1`, `healthModelVersion`, `healthProbabilities`, and
`mostLikelyHealthState` are null. They remain in the response for a future
validated learned estimator. Do not treat `rules_based` as model confidence.

| Health | Band      |
| -----: | --------- |
| 85–100 | `good`    |
|  65–84 | `fair`    |
|  40–64 | `poor`    |
|   0–39 | `failing` |
|   none | `unknown` |

The displayed estimate can be older than the page load time. Read
`healthEvaluatedAt` as the time Polymorfa last estimated Health.

## When Health is unavailable

`health` is `null` and `band` is `unknown` when Polymorfa cannot return a
supported present estimate. The response sets `healthSource: "unavailable"`,
`healthReliability: "unavailable"`, and an unavailable reason when known:

| Reason                        | Meaning                                                             |
| ----------------------------- | ------------------------------------------------------------------- |
| `no_active_model`             | No learned model is active when the learned estimator is selected.  |
| `invalid_active_model`        | The selected learned model did not pass runtime validation.         |
| `insufficient_fresh_features` | The number does not have enough fresh evidence for this evaluation. |

A response for a number that has never been evaluated has null Health metadata
and no unavailable reason. Do not render null as zero: zero is the lowest valid
Health estimate.

## Observed account state is separate

`observedAccountState` reports a state Polymorfa directly observed through an
account check or restriction event. It contains `state`, `observedAt`, and a
customer-readable `source`. It is not inferred from Health, and Health is not
replaced by the observed state.

Recorded findings and Polymorfa restrictions are separate diagnostics. The
rules-v1 Health runtime does not refresh retained finding rows, so read each
finding's `lastSeenAt` before acting on it. Their former point values are not
presented as current Health.

## Health history

`GET /platform/bansafe/health/{session}/history` returns accepted evaluations for
that number. Each point carries the same source, estimator version, coverage,
reliability, explanation, and observed-state fields. It does not join retired
scores or warm-up send totals into the series.

## Project Health rules

A project Health rule can act when a fresh, available Health estimate is lower
than the chosen threshold. Equality does not trigger it. Available actions are:

* stop the session while retaining linked credentials;
* slow sending to a configured rate;
* log out and require pairing again; and
* send an email or `bansafe.health_threshold` webhook. The webhook option
  requires an enabled project-wide native endpoint subscribed to this event or
  to all events.

Unknown or stale Health triggers no action. See [Safety in Console](/console/safety#health-rule)
for configuration and action semantics.

`GET /platform/bansafe/health-actions?projectId={projectId}` returns what each rule
action did. It reports the action, public status and outcome, triggering Health
and threshold, estimator provenance, and completion time. It does not expose
worker leases, retries, runtime identifiers, or free-form internal outcomes.

## Reporting a ban yourself

If WhatsApp restricts a number and Polymorfa did not observe it, use **Report a
ban** on the Safety page or `POST /platform/bansafe/incidents`. The report becomes an
observed incident; it does not directly set or replace Health. Use a stable
`Idempotency-Key` when retrying the request.

## Privacy boundary

Polymorfa uses operational counts, timing distributions, connection outcomes,
and account-state checks from your own linked session. It does not use message
text, media, recipient identifiers, or chat history to estimate Health.

Optional device evidence can be unavailable when a report reaches collection
limits. Absence of that evidence does not establish which device caused an
outcome, so Polymorfa does not infer confident attribution from the absence.

## Webhooks

`bansafe.health_threshold` is emitted when a configured project rule queues an
action for a fresh Health estimate below its threshold. The payload carries the
session and project, Health and threshold, estimator, model, and policy versions, evaluation
time, and stable episode and action IDs. Deduplicate retries by the webhook
envelope ID, which is the action ID.

Provider enforcement, incident, claim, and Polymorfa action events remain
separate facts. See [Webhooks](/api/webhooks#bansafe-events).