Monitoring Cormorant's status

Cormorant publishes the health of its subsystems — search, fetch, browser rendering, archive, paid tiers, batch jobs and storage — so you can watch it from your own monitoring and tell "our pipeline is broken" from "Cormorant is having a problem". People can read the same information at /status; machines read GET /v1/status.

No API key is needed, and the answer is shared by everyone and refreshed at most every 15 seconds, so polling it costs you nothing against your project's rate limit.

Quick start#

# Tiny body for uptime monitors
curl -s https://api.cormorant.ch/v1/status/summary
# {"status":"operational","description":"All systems operational","updated_at":"…"}

# Everything: components, reasons, metrics, incidents, maintenance
curl -s https://api.cormorant.ch/v1/status

What to poll, and how often#

• Uptime monitors (Uptime Kuma, Better Stack, Pingdom, a cron job): GET /v1/status/summary and a keyword check for "status":"operational".
• Your own dashboards and alerting: GET /v1/status, then look at the components your integration depends on (search, fetch, batch_jobs, …). Company data sources are listed one per source in the group company_data (company_gleif, …); a degraded source only means fresher data from it may be delayed — the company register still answers.
• Interval: every 30–60 seconds. Polling more often only returns the same snapshot (Cache-Control: public, max-age=15); send If-None-Match with the last ETag to get a 304 when nothing changed. More than 120 requests per minute from one IP address get 429.

Why the status endpoints always answer 200#

The HTTP code says whether Cormorant answered; the body says how it is doing. A status endpoint that returned 503 during an outage could not be told apart from a broken proxy, a DNS problem or your own network. So:

Recommended alert rules#

1. Unreachable: 3 consecutive failed checks (timeout 10 s) → critical.
2. Outage of what you use: a component you depend on is partial_outage or major_outage in 2 consecutive checks → critical.
3. Degradation: a component you use is degraded for 10 minutes → warning. Short blips are normal: status is computed from the last 10 minutes of traffic.
4. Incidents: a new entry in incidents with status other than resolved → notify your team with its title and latest updates.
5. Do not alert on a component that is missing: components not part of the deployment are not listed. Use the stable id, never name.

reasons says why a component is not operational (no_workers, queue_lag, low_success_rate, …) and metrics gives the numbers behind it, e.g. the fetch success rate or the age of the oldest waiting request.

Example: check from Python#

import httpx

r = httpx.get("https://api.cormorant.ch/v1/status", timeout=10)
r.raise_for_status()  # non-200: Cormorant unreachable
status = r.json()
mine = {c["id"]: c for c in status["components"] if c["id"] in ("search", "fetch")}
for c in mine.values():
    if c["status"] in ("partial_outage", "major_outage"):
        print(f"ALERT {c['name']}: {c['status']} ({', '.join(c['reasons'])})")
for incident in status["incidents"]:
    if incident["status"] in ("investigating", "identified", "monitoring"):
        print(f"Incident: {incident['title']} — {incident['updates'][0]['message']}")

Incidents, maintenance and history#

The operator posts incidents (with an impact and a timeline of updates) and announces maintenance windows; both appear in GET /v1/status and on the status page. During an announced window the affected components show maintenance rather than an outage. GET /v1/status/history?hours=24 gives the worst status per 5 minutes for the last 24 hours (hourly up to 7 days) and the uptime per component — useful for SLA reports.

Reference#

Public status of the service for your monitoring, and the page at /status. No authentication (an Authorization header is accepted and ignored), CORS-enabled, refreshed at most every 15 s and shared by all callers (Cache-Control: public, max-age=15, ETag / If-None-Match → 304). Limited to 120 requests per minute per client IP (429 with Retry-After). The status never contains host names, addresses, instance URLs, project names, keys or internal error strings — only component ids, statuses, reason codes and aggregate numbers.

The status endpoints answer 200 whatever the service status: the status is in the body. Alert on the body (status is not operational), and treat a timeout, a connection error or any other HTTP code as "Cormorant is unreachable" — a status endpoint that answered 503 during an outage could not be told apart from a broken proxy or network in between.

{
  "status": "degraded",
  "description": "Degraded performance",
  "updated_at": "2026-10-19T09:41:15+00:00",
  "window_s": 600,
  "components": [
    {"id": "api", "name": "API", "description": "…", "status": "operational", "reasons": [], "metrics": {}, "group": null},
    {"id": "fetch", "name": "Fetch", "description": "…", "status": "degraded", "reasons": ["low_success_rate"], "metrics": {}, "group": null},
    {"id": "company_gleif", "name": "Company data: GLEIF", "description": "…", "status": "operational", "reasons": [], "metrics": {}, "group": "company_data"}
  ],
  "incidents": [
    {"id": "inc_3f9a1c0b7e", "title": "Elevated fetch failures", "status": "identified",
     "impact": "degraded", "components": ["fetch"], "created_at": "…", "updated_at": "…",
     "resolved_at": null, "updates": [{"at": "…", "status": "identified", "message": "…"}]}
  ],
  "maintenance": []
}

Statuses, best to worst: operational, maintenance, degraded, partial_outage, major_outage. The overall status is the worst component status, except that a major outage of a component other than api, search, fetch or storage counts as a partial outage, and it is maintenance when the only components not operational are under announced maintenance. An unresolved incident shows its components at least at its impact. Components not part of the deployment are not listed (archive when archived copies are disabled, paid_tiers when no paid tier is configured, sec while no SEC identity is configured) — do not alert on a missing component.

Queue lag (queue_lag_s, sync_queue_lag_s: how long the oldest synchronous request has waited for a worker) above 15 / 60 / 120 s is degraded / partial / major. Rates computed on fewer than 20 requests (10 tier attempts) are reported but do not change a status. New metric keys may be added.

Reason codes: no_workers, queue_lag, low_success_rate, high_latency, engines_reduced, engines_unavailable, tier_errors, scheduler_stalled, jobs_waiting, database_unreachable, cache_unreachable, object_storage_unreachable, sec_backoff, throttled, incident, maintenance; company data sources also canary_failed, source_backoff, schema_drift, parse_failures.

Incidents and maintenance are posted by the operator. incidents lists unresolved incidents (investigating, identified, monitoring) and those resolved within 7 days, newest first, each with its timeline (updates, newest first). maintenance lists scheduled and in_progress windows and those completed within 7 days, soonest first; an empty components list means the whole service.

History: GET /v1/status/history returns, per component, statuses (oldest first; null where nothing was recorded) and uptime over the period, where a partial_outage bucket counts as 30 % downtime and a major_outage bucket as 100 %. Kept 7 days.