# Get PIX Health

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.

Endpoint: GET /health/pix
Version: 2.2.0
Security: bearerAuth

## Header parameters:

  - `ApplicationToken` (string, required)
    Fixed GUID that uniquely identifies your integration. Provided during ConnectPSP onboarding.
    Example: "{{ApplicationToken}}"

## Response 200 fields (application/json):

  - `schemaVersion` (integer)
    Contract version of this payload. Additive changes never bump it.
    Example: 1

  - `generatedAt` (string)
    When the engine produced this picture (UTC).
    Example: "2026-09-08T16:53:00Z"

  - `dataFreshnessSeconds` (integer)
    Age of the newest 5-minute window the engine evaluated, in seconds.
    Example: 480

  - `stale` (boolean)
    true when the picture is older than 3 minutes — the engine is late or stopped, and the
last known payload is still being served.

  - `overallStatus` (string)
    Health status. UNKNOWN means not enough sample to judge — never a failure. ROUTED_AWAY
(partners only) means the partner has no traffic because volume was routed elsewhere.
    Enum: "HEALTHY", "DEGRADED", "SEVERELY_DEGRADED", "UNAVAILABLE", "UNKNOWN", "ROUTED_AWAY"

  - `platform` (object)
    The ConnectPSP platform as a whole. An operation is null when there is no data for it in the window.

  - `platform.cashIn` (any)

  - `platform.cashOut` (any)

  - `partners` (array)
    The settlement partners in your scope: the ones you route through plus the ones you hold an
active account with, even with no traffic of yours in the window. Use routing to tell them apart.

A partner you only hold an account with is reported with its real health, but it never affects
your overallStatus and never raises an incident or a webhook for you.

"Active account" means an account seen in the last 30 days. Accounts are never deleted from our
records, so a partner you stopped using more than 30 days ago drops off this list.

  - `partners.ispb` (string)
    8-digit ISPB of the partner.
    Example: "20018183"

  - `partners.name` (string)
    Official bank name.
    Example: "STARK BANK"

  - `partners.routing` (boolean)
    Are you routing through this partner in the current window?

true — your PIX traffic goes through it. It counts towards your overallStatus and can raise
incidents and webhooks for you.

false — you hold an active account with it, but none of your PIX went through it in this window.
The health reported here is the partner's real health, measured across the whole platform, so you can
watch a partner you may switch back to at any time. It does not count towards your
overallStatus, and it raises no incident and no webhook for you.

A partner you have not held an account with for over 30 days is not reported at all.
    Example: true

  - `partners.share` (number)
    How much of your own PIX traffic was routed through this partner over the last 30 days, as a
fraction between 0 and 1. Your number, not the platform's. 0 when there is no reading — the
normal value for a partner with routing: false.
    Example: 1

  - `banks` (array)
    The banks your payers paid from, or your payees received at, over the last 30 days — crossed
with the ones the engine watches. A bank you have not transacted with in 30 days is not listed.

The engine watches the 20 largest institutions by platform volume. Below that, an institution sends
too few operations for any verdict to be meaningful, so it is left out rather than reported as
permanently UNKNOWN.

Sorted worst-first, then by your own share, then by name.

  - `banks.ispb` (string)
    Example: "18236120"

  - `banks.share` (number)
    How much of your own PIX traffic went through this bank over the last 30 days, as a fraction
between 0 and 1. It is your number, not the platform's — we never report other merchants' volume.

Used to sort the list, and useful to weigh how much a given bank's health matters to you.
0 when there is no reading.
    Example: 0.2814

  - `merchant` (any)
    Your own operation, judged against your own history. null when you had no traffic in the window.

  - `incidents` (array)
    Confirmed incidents open right now on ConnectPSP or on your settlement partners.

  - `incidents.incidentId` (string)
    Stable id. Use it to correlate the webhooks and the detail endpoint.
    Example: "LIVE-202609081530-PAYER_INSTITUTION-00360305"

  - `incidents.origin` (object)
    Who the incident is attributed to.

  - `incidents.origin.type` (string)
    - CONNECTPSP — the platform as a whole.
- BANKING_PARTNER — a settlement partner you route through (id = ISPB).
- PAYER_INSTITUTION — a bank your payers pay from / your payees receive at (id = ISPB).
- PAYER_COHORT — a group of payer banks with the same behaviour.
- MERCHANT — your own operation (id = your customer id).
- PIX_SYSTEMIC — the PIX system itself (DICT, SPI).
    Enum: "CONNECTPSP", "BANKING_PARTNER", "PAYER_INSTITUTION", "PAYER_COHORT", "MERCHANT", "PIX_SYSTEMIC"

  - `incidents.origin.id` (string)
    Example: "00360305"

  - `incidents.origin.displayName` (string)
    Example: "CAIXA ECONOMICA FEDERAL"

  - `incidents.operation` (string)
    CASH_IN = payments you receive; CASH_OUT = withdrawals you send.
    Enum: "CASH_IN", "CASH_OUT"

  - `incidents.status` (string)
    ACTIVE = confirmed and ongoing. WORSENING = severity went up. RECOVERING = metrics back to
normal, waiting 3 windows to close. RESOLVED = closed.
    Enum: "ACTIVE", "WORSENING", "RECOVERING", "RESOLVED"

  - `incidents.severity` (string)
    How bad it is (never HEALTHY on an incident).
    Enum: "DEGRADED", "SEVERELY_DEGRADED", "UNAVAILABLE"

  - `incidents.confidence` (string)
    How sure the engine is about who is at fault — not about how bad it is.
    Enum: "LOW", "MEDIUM", "HIGH"

  - `incidents.originClass` (string)
    How the engine knows. OBSERVED = it saw the error itself. INFERRED = deduced from the absence of
what should have happened. CORROBORATED / CONFIRMED = backed by a second independent signal.
    Enum: "OBSERVED", "INFERRED", "CORROBORATED", "CONFIRMED", "UNKNOWN"

  - `incidents.startedAt` (string)
    Start of the first anomalous window (UTC).
    Example: "2026-09-08T15:30:00Z"

  - `incidents.detectedAt` (string)
    When the engine confirmed it (UTC).
    Example: "2026-09-08T15:37:59Z"

  - `incidents.recoveredAt` (string,null)
    When metrics returned to normal; null while ongoing.

  - `incidents.resolvedAt` (string,null)
    When the incident was closed; null while open.

  - `incidents.updatedAt` (string,null)
    Example: "2026-09-08T16:52:00Z"

  - `incidents.affectedPartners` (integer)
    How many settlement partners the incident reached.
    Example: 2

  - `incidents.summary` (string)
    Diagnosis in Portuguese, written for you. Never contains other clients' data.
    Example: "Forte evidência de degradação em cobranças pagas por clientes da CAIXA ECONOMICA FEDERAL: a conversão desses pagadores ficou em 78,5%, contra 93,0% esperados, enquanto 9 instituições de controle seguem normais."

  - `externalIncidents` (array)
    Confirmed incidents open right now on payer banks or on the PIX system itself. These are
outside ConnectPSP's control and never downgrade overallStatus.

## Response 401 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type. It can contain non-ASCII characters.
    Example: "https://doc.connectpsp.com/errors/duplicated-external-reference"

  - `title` (string)
    Short, human-readable summary.
    Example: "Referência Externa Duplicada"

  - `status` (integer)
    HTTP status code.
    Example: 409

  - `code` (string)
    Machine-readable error code for programmatic handling. Absent on the 401 for a missing or
invalid ApplicationToken.
    Example: "DUPLICATED_EXTERNAL_REFERENCE"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "Já existe uma operação com o externalReference informado: withdraw_xyz789."

  - `errors` (object)
    Only on VALIDATION_ERROR. Field name → list of validation messages for that field.

  - `instance` (string)
    Request path where the error occurred. Present on some errors, such as INTERNAL_ERROR.

  - `traceId` (string)
    Only on INTERNAL_ERROR. Send it to support to locate the occurrence.

## Response 503 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type. It can contain non-ASCII characters.
    Example: "https://doc.connectpsp.com/errors/duplicated-external-reference"

  - `title` (string)
    Short, human-readable summary.
    Example: "Referência Externa Duplicada"

  - `status` (integer)
    HTTP status code.
    Example: 409

  - `code` (string)
    Machine-readable error code for programmatic handling. Absent on the 401 for a missing or
invalid ApplicationToken.
    Example: "DUPLICATED_EXTERNAL_REFERENCE"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "Já existe uma operação com o externalReference informado: withdraw_xyz789."

  - `errors` (object)
    Only on VALIDATION_ERROR. Field name → list of validation messages for that field.

  - `instance` (string)
    Request path where the error occurred. Present on some errors, such as INTERNAL_ERROR.

  - `traceId` (string)
    Only on INTERNAL_ERROR. Send it to support to locate the occurrence.


## Response 204 fields