# Health

**PIX Health** tells you whether PIX is working *for you* right now, and who is at fault when it is not.

A statistical engine compares every 5-minute window of your PIX traffic with what is normal for that
weekday and time over the last four weeks, and attributes any clear deviation to the platform, to a
settlement partner, to a payer bank or to your own operation — always scoped to what you actually use.

Three endpoints, all read-only and all safe to poll once a minute:

| Endpoint | Use it for |
|---|---|
| `GET /health/pix` | The picture of the moment: status per block plus the incidents open right now |
| `GET /health/pix/incidents` | History of confirmed incidents, paginated |
| `GET /health/pix/incidents/{id}` | One incident with the evidence behind the verdict |

None of them require `DigitalSignature` or `X-Idempotency-Key` — only `Authorization` and `ApplicationToken`.

Confirmed incidents are also pushed as webhooks (`PIX_INCIDENT_DETECTED` / `UPDATED` / `RESOLVED`), so you
do not have to poll to be warned; see the [Webhooks guide](/guides/webhooks#pix-health-events).


## Get PIX Health

 - [GET /health/pix](https://docs.connectpsp.com/apis/health/getpixhealth.md): Returns the current picture of the PIX network as it affects your operation, in four blocks:
platform (ConnectPSP), partners (the settlement partners you route through), banks (the banks
your payers pay from and your payees receive at) and merchant (your own operation). Each block
has a cashIn and a cashOut side with a health status and the verdict of every metric behind
it — plus the confirmed incidents open right now.

The picture is produced every minute by our detection engine, which compares every metric of
every 5-minute window with what is normal for that weekday and time of day over the last
four weeks. Only a statistically clear deviation becomes an anomaly; the size of the drop sets
the severity. It is cached for 60 seconds on our side, so polling once a minute is safe.

## Scoped to you

You only see what is in your scope. A partner you do not route through does not appear, and
overallStatus is computed from your partners only: if a partner you do not use is degraded,
your overall status stays HEALTHY. Banks appear only when your payers or payees use them.
No platform volumes or other clients' data are ever included — only statuses and verdicts.

## Reading the statuses

| Status | Meaning |
|---|---|
| HEALTHY | Within the normal range for this weekday and time |
| DEGRADED | Clearly worse, still working (for example, a 20 % drop in payments) |
| SEVERELY_DEGRADED | Much worse — half or more of what should be happening is not |
| UNAVAILABLE | Practically stopped |
| UNKNOWN | Not enough sample in this window to say anything — not a failure |
| ROUTED_AWAY | A partner with no traffic because volume was routed elsewhere — unknown, not down |

overallStatus is the worst of the ConnectPSP platform and your settlement partners, plus any
confirmed incident on them. Payer banks and your own operation never downgrade it.

### UNKNOWN is not a failure

It is the single most misread value here, so to be explicit: UNKNOWN means the engine does not
have enough evidence to judge, never that something is wrong.

Every verdict is a comparison against what is normal for that entity, on that weekday, at that time of
day. Two things produce UNKNOWN:

- Too few operations in the window. Common on a quiet bank overnight, or on a low-volume one at any
  hour. Nothing is broken — there is simply not enough to measure.
- No baseline yet. The engine needs about four weeks of history for an entity before it can say what
  "normal" looks like. A bank it started watching recently reads UNKNOWN until that history builds up.

Our own screens label this state "Calibrando" (calibrating) rather than "unknown", for the same
reason. Treat it as "no reading", not as a red flag — and never as an outage.

## Signals

Every cashIn / cashOut carries signals: the metric name and its verdict — NORMAL, LOW (below
expected), HIGH (above expected) or UNKNOWN (no sample). For counts and success rates LOW
is the bad side; for error rates and latencies HIGH is the bad side.

## Two different clocks

Do not confuse the two age fields — they answer different questions:

| Field | Question it answers |
|---|---|
| generatedAt / stale | Is the picture itself fresh? stale: true means it is older than 3 minutes — the engine is late or stopped and we are still serving the last known payload |
| dataFreshnessSeconds | How old is the newest traffic window behind it? Normally several minutes, because some metrics (such as CONVERSION_MATURED) only make sense after a QR code has had time to be paid |

So dataFreshnessSeconds: 480 together with stale: false is the normal case, not a contradiction:
a fresh picture about a window that closed 8 minutes ago. Alert on stale, not on dataFreshnessSeconds.

This endpoint does not require DigitalSignature or X-Idempotency-Key.

## List PIX Incidents

 - [GET /health/pix/incidents](https://docs.connectpsp.com/apis/health/listpixincidents.md): Confirmed PIX incidents in your scope, most recent first, paginated. An incident is confirmed
when the engine saw the same pattern in two consecutive 5-minute windows; a one-window blip never
appears here. Defaults to the last 7 days; the window between from and to cannot exceed 92 days.

Each incident tells you who (origin), how bad (severity), how sure we are about the
culprit (confidence) and how we know (originClass: OBSERVED = we saw the error,
INFERRED = deduced from the absence of what should have happened). summary is a diagnosis in
Portuguese written for you — never internal counts of other clients.

## One flat list

Unlike GET /health/pix, which splits the open incidents into incidents and externalIncidents,
this list is flat. Use origin.type to tell the two apart: CONNECTPSP and BANKING_PARTNER
are ours to fix, PAYER_INSTITUTION / PAYER_COHORT / PIX_SYSTEMIC are outside our control, and
MERCHANT is your own operation.

status is matched case-insensitively, so active,worsening works too. The response echoes back
the from and to actually applied, so you can log the window you really got.

This endpoint does not require DigitalSignature or X-Idempotency-Key.

## Get PIX Incident

 - [GET /health/pix/incidents/{id}](https://docs.connectpsp.com/apis/health/getpixincident.md): One incident with the evidence behind the verdict. Each piece of evidence names the metric, the
entity, the relative deviation from expected and the Z-score — never raw platform volumes.

Returns 404 when the incident does not exist or is outside your scope; the two cases are
deliberately indistinguishable.

This endpoint does not require DigitalSignature or X-Idempotency-Key.