Get subscription delivery health

Returns a consolidated, non-secret delivery-health rollup for one subscription — the “why did this tenant stop receiving events” view. The existence gate runs first, so an absent, soft-deleted, or cross-tenant id returns a uniform 404 not_found. Outcome counts are a recent-window view, not an all-time tally.

GET /v1/subscriptions/{id}/health

Get subscription delivery health

cURL

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

200

{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "enabled": true,
  "delivery_outcomes": {},
  "recent_outcomes": {},
  "success_rate": 123,
  "dead_lettered": 123,
  "poison_events": 123,
  "dropped_tenant": true,
  "consumer_lag_ms": 123,
  "auto_disabled": true,
  "disabled_reason": "<string>",
  "last_success_at": "2023-11-07T05:31:56Z",
  "last_failure_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

A bearer JWT issued by plugin-auth (lib-auth). The tenant identity is resolved from the validated token claims; the /v1 surface never reads a tenant from the body, path, or query. Machine callers obtain a token via the plugin-auth client-credentials flow. The /admin surface authorizes against an operator scope and carries no tenant context.

Path Parameters

id · string<uuid> · required

The unique identifier of the subscription (UUIDv7).

Response

200

application/json

The delivery-health rollup.

The consolidated, non-secret delivery-health rollup for one subscription.

subscription_id · string<uuid> · required

The subscription the rollup describes.

Example:

"0192f1a0-0000-7000-8000-00000000a001"

enabled · boolean · required

The operator on/off flag.

Example:

true

verification_state · enum<string> · required

The subscription's position in the destination verification state machine. Only an active subscription is deliverable. A pull subscription is born active — it has no destination to probe. Every other kind is born pending_verification and reaches active on a successful probe: POST /v1/subscriptions/{id}/ping for a webhook, and PUT /v1/subscriptions/{id}/credential for any queue sink (sqs, rabbitmq, eventbridge). An sqs or eventbridge sink has a second path: register a delegated grant — which persists the coordinates and leaves this field unchanged — then call POST /v1/subscriptions/{id}/verify. An active subscription whose probe later fails becomes degraded. The same successful probe returns this field to active. This field is one half of deliverability: enabled is the other half, and both must hold. No probe changes enabled except POST /v1/subscriptions/{id}/verify, which on a probe success clears an auto-disable in the same transaction as the state move.

Available options: pending_verification, active, degraded

status · enum<string> · required

The rolled-up delivery-health verdict. Down means the subscription was auto-disabled by the system (the endpoint is judged broken); Degraded means a lesser impairment (a manual disable, dead-lettered attempts, or dropped tenant events); Healthy otherwise.

Available options: Healthy, Degraded, Down

delivery_outcomes · object · required

Delivery-attempt outcome counts over the configured recent window (keyed by outcome, e.g. delivered, failed, dead_lettered). Always an object, never null.

Show child attributes

Example:

{
  "delivered": 7,
  "failed": 2,
  "dead_lettered": 1
}

recent_outcomes · object · required

The same outcome histogram restricted to the last 24 hours (a subset of delivery_outcomes). Always an object; an outcome with no recent activity is simply a missing key.

Show child attributes

Example:

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

success_rate · number | null · required

The derived per-attempt delivery rate over the window (delivered / (delivered + failed + dead_lettered)), in [0.0, 1.0]. null when there are zero terminal attempts (distinct from a genuine 0.0). Per-attempt, not per-job, and informational only — it does not change status.

Example:

0.7

dead_lettered · integer · required

The count of dead-lettered attempts in the window.

Example:

1

poison_events · integer · required

A best-effort count of quarantined (poison) events keyed on the untrusted captured tenant id; drives dropped_tenant.

Example:

3

dropped_tenant · boolean · required

True when quarantined tenant events were observed.

Example:

true

consumer_lag_ms · integer<int64> · required

Process consumer lag in milliseconds; 0 when no lag-as-time source is exposed.

Example:

12000

auto_disabled · boolean | null · required

The auto-disable verdict: null when the subscription has no recorded attempts yet, false when a health row exists with no verdict, true when auto-disable has tripped (which drives status: "Down").

Example:

true

disabled_reason · string

A fixed, secret-free auto-disable verdict token (e.g. consecutive_failures). Omitted when empty.

Example:

"consecutive_failures"

last_success_at · string<date-time>

The last successful delivery timestamp (RFC 3339). Omitted when none.

Example:

"2026-06-01T12:00:00Z"

last_failure_at · string<date-time>

The last failed delivery timestamp (RFC 3339). Omitted when none.

Example:

"2026-06-05T09:30:00Z"