Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.minerva.io/llms.txt

Use this file to discover all available pages before exploring further.

mc.status.health() probes Minerva’s API endpoints to confirm they’re reachable and healthy. The probe is unauthenticated (works without an API key) and never raises — failures are returned as values, so you can call it in a polling loop without try/except. 
from minerva import Minerva

mc = Minerva()                      # no API key needed for health probes
report = mc.status.health()
# -> {"api": HealthStatus(ok=True, latency_ms=42.0, status_code=200, status="ok", message=None, error=None)}

​
Why use it

Use caseWhat health() gives you
Polling liveness from a monitor / cron / Prometheus exporterok + latency_ms per endpoint
Debugging “is my key wrong, or is the API down?”Probe works without an API key — if ok=True, the API is fine; the issue is your key
Pre-flight at process startupOne quick call before kicking off batches

​
Return shape

Always a dict[str, HealthStatus] keyed by endpoint name. One entry today ("api"); the dict grows as Minerva exposes more endpoints. Iterating today’s code keeps working as endpoints come online. 
for name, h in mc.status.health().items():
    if not h.ok:
        alert(f"{name} is down: {h.error} (HTTP {h.status_code})")
    else:
        log(f"{name} up — {h.latency_ms:.0f} ms")

​
HealthStatus

​
ok
bool
True when the endpoint is reachable and reports healthy (HTTP 2xx and status == "ok" in the body, when present).
​
latency_ms
float
Round-trip time for the probe, in milliseconds.
​
status_code
int | None
HTTP status code returned by the endpoint. None on network-level failure (DNS, TCP, TLS, timeout).
​
status
str | None
Value of the status field in the gateway’s response body, when present (e.g. "ok", "degraded"). None if the body had no such field.
​
message
str | None
Optional human-readable detail from the gateway (e.g. "DB read replica lagging"). Populated when the server includes a message field in its body, regardless of ok.
​
error
str | None
SDK-side description of why ok=False — the HTTP code (e.g. "HTTP 503") or the underlying network exception class (e.g. "ConnectError: ..."). None when the probe succeeded. Distinct from message: error is the SDK’s reason for marking ok=False; message is whatever the gateway itself returned.

​
Parameters

​
endpoints
str | list[str] | None
Which endpoint(s) to probe. Omit (or pass None) to probe every known endpoint. Pass a single name or a list of names to filter. Today the only known name is "api"; unknown names raise ValueError.
​
timeout
float
default:"5.0"
Per-endpoint timeout in seconds. Default 5 — for a liveness check, “no answer in 5 seconds” is itself a useful answer.

​
Examples

Probe everything (default): 
mc.status.health()
# -> {"api": HealthStatus(ok=True, ...)}
Probe a single endpoint (still returns a dict): 
mc.status.health(endpoints="api")
# -> {"api": HealthStatus(ok=True, ...)}

mc.status.health(endpoints=["api"])
# -> {"api": HealthStatus(ok=True, ...)}
Polling loop: 
import time
from minerva import Minerva

mc = Minerva()
while True:
    for name, h in mc.status.health().items():
        if not h.ok:
            page_oncall(f"Minerva {name}: {h.error}")
    time.sleep(30)
Prometheus exporter: 
from prometheus_client import Gauge

up = Gauge("minerva_endpoint_up", "1 if up", ["endpoint"])
latency = Gauge("minerva_endpoint_latency_ms", "Probe latency", ["endpoint"])

def collect():
    for name, h in mc.status.health().items():
        up.labels(endpoint=name).set(1 if h.ok else 0)
        latency.labels(endpoint=name).set(h.latency_ms)
Distinguish “API down” from “key invalid”: 
report = mc.status.health()
if not report["api"].ok:
    print("API is down — try again later")
else:
    try:
        mc.api.enrich([{"record_id": "1", "linkedin_url": "..."}])
    except MinervaAuthError:
        print("API is fine — your key is the problem")

​
Authentication

The probe is unauthenticated — mc.status.health() does not send x-api-key. You can construct Minerva() without an API key purely to run health probes: 
mc = Minerva(api_key="not-needed-for-health")
mc.status.health()       # ok
mc.api.enrich([...])     # this would fail — the data API requires a real key

​
Errors

health() itself never raises for probe failures — the outcome is encoded in the returned HealthStatus (ok=False with error set). The only thing that raises is misuse of the call itself:
ConditionRaises
Unknown name in endpoints=ValueError
Bad timeout= (e.g. negative)TypeError / ValueError (from httpx)