Org-wide rollup

Returns every AWS account connected to your organization, plus a top-level rollup: the worst status across all of them wins.

curl https://api.wraps.dev/v1/account/health \  -H "Authorization: Bearer wraps_your_api_key"

{  "status": "at_risk",  "checkedAt": "2026-09-04T09:00:00.000Z",  "accounts": [    {      "id": "aws-acc-123",      "accountNumber": "123456789012",      "region": "us-east-1",      "status": "at_risk",      "checkedAt": "2026-09-04T09:00:00.000Z",      "sandbox": false,      "productionAccessEnabled": true,      "sendingEnabled": true,      "enforcementStatus": "HEALTHY",      "quota": {        "max24Hour": 50000,        "sentLast24Hours": 41230,        "usedRatio": 0.8246,        "maxSendRate": 14      },      "reputation": {        "bounceRate": 0.004,        "complaintRate": 0.0001      },      "thresholds": {        "bounceReview": 0.05,        "bouncePause": 0.10,        "complaintReview": 0.001,        "complaintPause": 0.005,        "quotaWarn": 0.8      },      "reasons": ["quota_high"]    }  ]}

Single account

GET /v1/account/health/:awsAccountId returns the same per-account shape for exactly one connected account, org-scoped — a request naming an account that belongs to another organization, or that does not exist, returns 404.

curl https://api.wraps.dev/v1/account/health/aws-acc-123 \  -H "Authorization: Bearer wraps_your_api_key"

Reading the status field

Every status is one of exactly four values, on both the per-account objects and the top-level rollup:

Why unknown is not healthy

An account nobody has been able to check is exactly the account most likely to be in trouble — treating it as healthy would be the exact lie this endpoint exists to avoid. The same rule applies to the org-wide rollup: unknown outranks healthy, so an org with one never-swept account and nine healthy ones still rolls up to unknown. The full ranking, worst first: in_danger > at_risk > unknown > healthy.

The same rule holds field by field: a never-swept account reports null for every rate, quota figure, and sandbox — never a measured-looking 0 or false.

Thresholds and headroom

thresholds on every account is AWS's own published review and pause lines — the same numbers Wraps compares against when it computes status, not numbers Wraps invented. A caller can compute its own headroom (e.g. thresholds.bouncePause - reputation.bounceRate) rather than waiting for the status to change.

Freshness: checkedAt

Every number here comes from the last completed hourly account-health sweep, not a live AWS read. checkedAt is the contract that keeps that honest — it is the timestamp of that sweep, per account and, on the rollup, the OLDEST timestamp among the accounts represented, so the freshness claim holds for every account the rollup speaks for. A verdict from over an hour ago usually just means the next sweep hasn't run yet; a verdict from much longer ago is worth investigating on its own.

• Poll this endpoint before a send, not instead of watching for in-band send failures — the verdict is at most an hour stale.
• An account that has never connected, or whose console-access role cannot be assumed, reports unknown — check /docs/guides/production-access if that persists.