Monitoring Cormorant's status

Cormorant publishes the health of its subsystems — API, search, fetch, browser rendering, archive, premium routes, SEC EDGAR, batch jobs, storage and each company data source — 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. The component ids are api, search, fetch, browser_rendering, archive, premium_routes, sec (SEC EDGAR: /v1/sec/… and fetches of SEC hosts; listed while SEC is configured), company_profiles (extended company profiles: profiles, discovery and company networks; listed while a premium route is configured), batch_jobs, storage, and one per active company data source in the group company_data (currently company_gleif, company_uid_register, company_zefix_rest, company_lindas_zefix, company_sogc, company_ch_cantonal_excerpt). A degraded company 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 (or the last hour, see below).
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.

Windows and minimum samples#

Rates need enough traffic to mean anything. Each component's metrics carries the counts behind its rate and the window they cover:

• The default window is the last 600 s (window_s at the top level and in each component's metrics).
• When a component has fewer than its minimum sample there — moderate or bursty load — it reports over the last 3600 s instead, with metrics.window_s: 3600 (proxy_window_s/rendering_window_s for the premium routes). Its status is judged on that window too.
• success_rate: null means even the hour is short of the minimum: no evidence either way, and the rate never changes the status then.
• At most the 20,000 most recent requests are read per window.

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, premium_routes when no premium route is configured, sec while no SEC identity is configured, company_profiles while no premium route is configured) — do not alert on a missing component.

Counts and rates cover the last window_s = 600 s. A component with fewer than its minimum sample there (20 uncached requests; 10 attempts for a tier) reports requests/attempts, failures and success_rate over the last hour instead; metrics.window_s (<tier>_window_s in premium_routes) says which window was used, and the status is judged on that window. null rates mean even the hour has too few samples.

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, provider_access, upstream_refusing, site_backoff, 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.