API
One JSON API, served two ways. The public edition is static files rewritten every few minutes, with no key and open CORS, so a browser can call it directly. A self-hosted server answers the same paths live from your own database.
https://dharmeshdev1.github.io/mercalli/api/v1/Conventions
- Every document carries
generated_at. - Times are UTC in ISO 8601 with a Z. Durations are minutes.
- Fields are only ever added within v1; nothing is renamed or removed.
- Self-hosted servers also stream changes as server-sent events at
/api/v1/stream.
Documents
Each one can be fetched live from here. Responses are shortened for display.
meta.json
Version, edition, counts, the last pipeline run, model and census versions.
overview.json
Everything the home page needs: counts, every service's health, open incidents with forecasts and blast radius, the last 48 hours of resolved incidents, and the seismograph series.
services.json
Every watched service with health, status page, domains and 90 day reliability.
services/<id>.json
One service: components, its incidents over 90 days, what it depends on and what depends on it.
No example yetincidents/<service>/<incident>.json
One incident: every update, every forecast made while it was open, the blast radius and similar past incidents. Kept for 14 days after it ends.
No example yetgraph.json
The dependency graph: services and providers as nodes, dependencies as edges with evidence.
model.json
The model card: how the forecasters were trained and how accurate they are.
census-summary.json
Shares of the top domains by DNS, edge, hosting provider, region, certificate authority and mail provider.
replays.json
Timelines of past cascades, reconstructed from status page history.
Atom feeds live at feeds/all.xml and feeds/<service>.xml.
Health, impact and status
health
The worst current state of a service's components. Unknown when its status page could not be read for 30 minutes.
operationalmaintenancedegradedpartial_outagemajor_outageunknown
impact
The vendor's own label for an incident, mapped from every provider's scale.
nonemaintenanceminormajorcritical
status
Where an incident is in its lifecycle.
investigatingInvestigatingidentifiedIdentifiedmonitoringMonitoringresolvedResolvedpostmortemPostmortem
Incident summary
Used in overview.json and services/<id>.json.
| Field | Meaning |
|---|---|
| id | service:incident, unique across Mercalli |
| path | Where the full incident document lives |
| impact, status | See the vocabulary above |
| started_at | Start, using the vendor's backdated start when it gave one |
| resolved_at | End, or null while open |
| resolved_inferred | True when the incident disappeared from the vendor's page without a resolution time, and Mercalli recorded the time it noticed |
| duration_min, elapsed_min | Length once resolved; time open so far |
| latest | The most recent vendor update: at, status, body |
| first_seen_at | When Mercalli first saw it, which can be later than started_at when a vendor backdates the start |
| forecast | The time left until the vendor marks it resolved: p10, p50 and p90 in minutes from made_at, with the matching clock times. The 10th to 90th range is an 80% interval, calibrated on held out data. Null for resolved incidents and incidents the model cannot score |
| blast | Services that may post an incident of their own because of this one, most likely first, with probability and evidence. Only computed for incidents at providers others depend on, null otherwise |
Seismograph
Part of overview.json: 48 hours of activity in 10 minute buckets.
| Field | Meaning |
|---|---|
| start, bucket_minutes, points | When the first bucket begins, how long each bucket is, and how many there are |
| series | Per provider: the weight of its worst open incident in each bucket |
| total | The weights of every open incident across all services, summed per bucket |
Weights: critical 3, major 2, minor 1, none 0.5, maintenance 0.25.
Graph
graph.json. An edge points from a dependent to what it depends on.
| Field | Meaning |
|---|---|
| nodes | id, name, category, kind (service or provider), health for watched services, and dependents |
| edges | source, target, kinds, weight, evidence |
| kinds | dns, edge or hosting from the census; named when the dependent's own reports name the provider; cofailure when the two fail together more often than chance |
Stream
Self-hosted only.
GET /api/v1/stream is a server-sent event stream. Each event is one of incident.opened, incident.updated, incident.resolved or forecast, with the incident summary as data.