Get a subscription's delivery health

Rolls one subscription’s delivery record into a single non-secret view: outcome counts over the hub’s window and over the last 24 hours, dead-lettered and poison-event counts, the auto-disable verdict, the success rate and the consumer lag.

It answers the question none of the other subscription reads can: whether the events this tenant subscribed to are ACTUALLY ARRIVING. Listing a subscription proves it is registered and enabled; only this shows whether the endpoint behind it has been accepting deliveries.

‘auto_disabled’ and ‘success_rate’ are NULLABLE and null is not the zero value of either. A null ‘auto_disabled’ means the hub holds no endpoint-health row yet, which is not the same fact as false (“checked, and healthy”). A null ‘success_rate’ means no delivery attempt has reached a terminal outcome yet, which is not the same fact as 0.0 (“every attempt failed”). A client that reads either null as its zero value reports a healthy endpoint as broken, or a broken one as fine.

‘disabled_reason’, ‘last_success_at’ and ‘last_failure_at’ are null when there is nothing to report, and the key is always present.

‘status’ and ‘verification_state’ are FREE strings carried through from the hub, not a closed vocabulary this gateway pins. The hub may add a value, and a client should render an unrecognized one by its identifier rather than refuse the response.

This is a FORWARD, not a local read: the gateway owns no subscription storage. The hub answers an unknown subscription and another tenant’s subscription with the SAME 404, publishing no existence oracle, and that 404 reaches the caller unchanged. This gateway does not reinterpret it, because splitting it into “no such subscription” and “not yours” would state something the hub deliberately refused to state.

The tenant is derived from the validated identity and is never read from the request.

GET /v1/subscriptions/{id}/health

Get a subscription's delivery health

cURL

curl --request GET \
  --url https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health \
  --header 'Authorization: Bearer <token>'

200

{
  "auto_disabled": false,
  "consumer_lag_ms": 120,
  "dead_lettered": 2,
  "delivery_outcomes": {
    "delivered": 128,
    "failed": 2
  },
  "disabled_reason": "consecutive_failures",
  "dropped_tenant": false,
  "enabled": true,
  "last_failure_at": "2026-01-15T09:29:00Z",
  "last_success_at": "2026-01-15T09:30:00Z",
  "poison_events": 0,
  "recent_outcomes": {
    "delivered": 40,
    "failed": 1
  },
  "status": "Healthy",
  "subscription_id": "0192f1a0-0000-7000-8000-0000000000ff",
  "success_rate": 0.98,
  "verification_state": "active"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

Authorization · string

Bearer token. A tenant route relays it to the streaming-hub as server-to-server auth.

Ejemplo:

"Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcHMifQ.signature"

Parámetros de ruta

id · string · requerido

Subscription id.

Ejemplo:

"0192f1a0-0000-7000-8000-0000000000ff"

Respuesta

200

application/json

OK

auto_disabled · boolean | null · requerido

Endpoint-health auto-disable verdict: null when the hub has no health row yet, false when healthy, true when tripped. Null is never false.

Ejemplo:

false

consumer_lag_ms · integer<int64> · requerido

Process consumer lag behind the high watermark, in milliseconds.

Ejemplo:

120

dead_lettered · integer<int64> · requerido

Count of dead-lettered delivery attempts in the window.

Ejemplo:

2

delivery_outcomes · object · requerido

Delivery-attempt outcome counts over the hub's configured window, keyed by outcome.

Show child attributes

Ejemplo:

{ "delivered": 128, "failed": 2 }

disabled_reason · string | null · requerido

Fixed, secret-free auto-disable verdict token; null when the subscription was not auto-disabled.

Ejemplo:

"consecutive_failures"

dropped_tenant · boolean · requerido

Whether any events were dropped or quarantined for this tenant.

Ejemplo:

false

enabled · boolean · requerido

Whether delivery is enabled (manual operator toggle).

Ejemplo:

true

last_failure_at · string<date-time> | null · requerido

Instant of the last failed delivery; null when there has never been one.

Ejemplo:

"2026-01-15T09:29:00Z"

last_success_at · string<date-time> | null · requerido

Instant of the last successful delivery; null when there has never been one.

Ejemplo:

"2026-01-15T09:30:00Z"

poison_events · integer<int64> · requerido

Count of quarantined poison events for this tenant.

Ejemplo:

0

recent_outcomes · object · requerido

Last-24h delivery-outcome breakdown, keyed by outcome.

Show child attributes

Ejemplo:

{ "delivered": 40, "failed": 1 }

status · string · requerido

Rolled-up operator status (Healthy, Degraded, Down, Paused). A free string, not a closed vocabulary.

Ejemplo:

"Healthy"

subscription_id · string · requerido

The subscription this health view is for.

Ejemplo:

"0192f1a0-0000-7000-8000-0000000000ff"

success_rate · number<double> | null · requerido

Share of terminal delivery attempts that succeeded, in [0.0, 1.0]; null when no terminal attempt has happened yet. Null is never zero.

Ejemplo:

0.98

verification_state · string · requerido

Position in the destination verification state machine (pending_verification, active, degraded, disabled). A free string, not a closed vocabulary.

Ejemplo:

"active"