Get a subscription's delivery health

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

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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

subscriptions

{id}

health

Get a subscription's delivery health

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

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://br-consignado-gw.sandbox.lerian.net/v1/subscriptions/{id}/health"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

Authorization

string

Bearer token, relayed to the streaming-hub as server-to-server auth.

Example:

"Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJvcHMifQ.signature"

Path Parameters

string

required

Subscription id.

Example:

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

Response

auto_disabled

boolean | null

required

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

Example:

false

consumer_lag_ms

integer<int64>

required

Process consumer lag behind the high watermark, in milliseconds.

Example:

120

dead_lettered

integer<int64>

required

Count of dead-lettered delivery attempts in the window.

Example:

2

delivery_outcomes

object

required

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

Show child attributes

Example:

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

disabled_reason

string | null

required

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

Example:

"consecutive_failures"

dropped_tenant

boolean

required

Whether any events were dropped or quarantined for this tenant.

Example:

false

enabled

boolean

required

Whether delivery is enabled (manual operator toggle).

Example:

true

last_failure_at

string<date-time> | null

required

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

Example:

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

last_success_at

string<date-time> | null

required

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

Example:

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

poison_events

integer<int64>

required

Count of quarantined poison events for this tenant.

Example:

0

recent_outcomes

object

required

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

Show child attributes

Example:

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

status

string

required

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

Example:

"Healthy"

subscription_id

string

required

The subscription this health view is for.

Example:

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

success_rate

number<double> | null

required

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

Example:

0.98

verification_state

string

required

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

Example:

"active"

Tenant setup and credentials

Worker data and margin

Auctions and proposals

Contract registration and documents

Contract corrections

Contract lifecycle

Refinancing, renegotiation, and portability

Legacy contracts

FGTS guarantees

Reconciliation and calendar

Funds and assignments

Capacity and usage

Monitoring

Event subscriptions

Error handling

Events

Get a subscription's delivery health

Authorizations

Headers

Path Parameters

Response