Health Checks

Allegro exposes two read-only HTTP endpoints designed to be polled by an external monitor (an uptime checker, a metrics scraper, or an on-call alerting system). One reports the health of a single tenant's queues; the other reports the health of the platform-wide job queues. Both return an HTTP 503 when their backing service can't be reached, so even a naive "is the status code 200?" check trips on a degraded state.

These endpoints are part of the REST API — see the REST API reference for the authoritative request and response schemas. This guide explains what they report and how to wire up monitoring against them.

Tenant health

GET /api/v1/health

Authenticated with a Sanctum bearer token; the token's user must be able to view the tenant. The endpoint reports the depth and oldest-item age of that tenant's Redis-backed queues — the Event Queue and the Heartbeat Queue.

{
    "status": "ok",
    "tenant": "tenant_123",
    "redis": { "reachable": true },
    "queues": {
        "events": { "depth": 0, "oldest_age_seconds": null },
        "heartbeats": { "depth": 12, "oldest_age_seconds": 34 }
    }
}

Field	Meaning
status	ok when Redis is reachable, degraded otherwise.
redis.reachable	Whether the queue's Redis backend responded.
queues.*.depth	Number of items currently waiting in the queue.
queues.*.oldest_age_seconds	Age in seconds of the oldest item still waiting, or null when the queue is empty.

When Redis cannot be reached, status is degraded, every queue value is null, and the response status code is 503.

A steadily rising depth or oldest_age_seconds means a consumer has fallen behind and is no longer draining the queue fast enough — see the Event Queue and Heartbeat Queue guides for how consumers read and delete items.

Platform health

GET /api/v1/landlord/health

Authenticated with a Sanctum bearer token belonging to a super admin, and served only in the landlord context. It reports the backlog of every background queue listed in allegro.queues, plus the failed-job count.

{
    "status": "ok",
    "queue": { "reachable": true },
    "queues": {
        "high": { "pending": 0 },
        "default": { "pending": 2 },
        "bulk": { "pending": 0 }
    },
    "failed_jobs": 0
}

Field	Meaning
status	ok when the queue backend is reachable, degraded otherwise.
queue.reachable	Whether the queue backend responded.
queues.*.pending	Number of jobs waiting on that queue. On managed queues this is SQS's approximate count, which lags a few seconds.
failed_jobs	Failed jobs across all queues in the last 7 days, or null if the failed-job driver cannot be counted.

Each queue is reported separately, keyed by its name. For what the high, default, and bulk queues carry, see Queue Management. When the backend is unreachable, status is degraded, queues is empty, failed_jobs is null, and the response status code is 503.

To enumerate the tenants a monitor should poll for tenant-level health, a super admin can list them with GET /api/v1/landlord/tenants.

Failed job window

queue:prune-failed --hours=168 runs daily, so failed_jobs is a rolling seven-day count rather than a lifetime total. Failures older than that are removed from the failed_jobs table and are no longer retryable.

Setting up monitoring

• Alert on the status code. Treat any non-200 (especially 503) as a page-worthy event — the endpoints are built so a plain HTTP check is enough.
• Trend the depths. A single high reading can be a momentary spike; a depth or backlog age that climbs across consecutive polls is a stuck consumer.
• Watch failed_jobs. A non-zero, growing count signals jobs erroring out rather than simply queuing.

note

Both endpoints require authentication, so configure your monitor with a Sanctum token. See REST API Authentication for how to issue one.