Health API for dashboards
A weekly SEO walk over a few thousand pages ends as one run with hundreds of findings. A dashboard does not want to download it and count again. These endpoints answer with the counts already made: per language, step (a stack step is one page template), check or pack, with the pages that are hit most, and what changed since the run before.
A token for the dashboard
Create a token with the read:health scope in Settings → API tokens (on Enterprise also as a service account). It reads the endpoints on this page and the rest of health (GET …/health of a run, a scenario or a project, MCP get_health); every other request answers 403. A token with the read scope works too.
curl -H "Authorization: Bearer $KALOKO_TOKEN" \
"https://kaloko.app/api/v1/orgs/acme/scenarios/seo-weekly/latest/health/aggregate?by=locale,step"
Endpoints
| Request | What it answers |
|---|---|
GET /api/v1/orgs/<org>/scenarios/<id>/latest | The newest shared run of a scenario you can see: its id, date, verdict, health counts and the links below. ?environment=production picks the newest run on one environment |
GET …/scenarios/<id>/latest/health/aggregate | The aggregate of that run, in one call |
GET …/scenarios/<id>/latest/health/diff | The diff of that run, in one call |
GET /api/v1/orgs/<org>/runs/<run>/health/aggregate | Counts per group with the most affected pages, and the diff's counts |
GET /api/v1/orgs/<org>/runs/<run>/health/diff | New, fixed and still open results, each with the run that first saw it |
GET /api/v1/orgs/<org>/scenarios/<id>/findings | Open results grouped into findings by check, site, language and step, with their status (below) |
MCP has the same as get_health_aggregate, get_health_diff (with run_id, or scenario and environment) and list_findings.
What is counted
One result is one page in one language for one check. A page walked on several viewports counts once, with its worst verdict. A stack step counts each of its pages; a plain step is its own page. A result is pass, fail, needs_review (the evaluator was unsure) or not_evaluated. Checks that do not apply to a page are left out.
Health is advisory: these numbers never change a step's or a run's verdict.
Aggregate
GET …/health/aggregate takes:
| Parameter | Meaning |
|---|---|
by | Comma-separated: locale, step, check, pack. Default locale,step,check. Empty groups everything into one |
locale, step, check, pack | Only results with this value |
top | Affected pages per group, 0 to 20 (default 5); failing pages come before unsure ones |
limit | Groups in the answer, 1 to 5000 (default 500), the most failing first |
{
"schema": "kaloko.health-aggregate.v1",
"run": { "id": "2026-10-12-seo-weekly-a1b2c3", "scenario": "seo-weekly", "title": "Weekly SEO", "project": "web", "environment": "production", "started_at": "2026-10-12T05:00:00.000Z", "canvas": "https://kaloko.app/acme/runs/2026-10-12-seo-weekly-a1b2c3/#health", "aggregate_url": "…", "diff_url": "…" },
"by": ["locale", "step", "check"],
"filter": {},
"totals": { "results": 16800, "pass": 15910, "fail": 812, "needs_review": 64, "not_evaluated": 14, "pages": 2800 },
"checks": { "HC112": { "text": "The page carries structured data (JSON-LD)", "pack": "seo", "level": "warning" } },
"diff": { "previous": { "id": "2026-10-05-seo-weekly-d4e5f6", "started_at": "2026-10-05T05:00:00.000Z" }, "new": 14, "fixed": 3, "still_open": 859, "unchecked": 0, "worse": 1, "expired": 0, "open": 876 },
"group_count": 168,
"truncated": false,
"groups": [
{
"id": "locale=pl;step=eshop;check=HC112",
"locale": "pl", "step": "eshop", "check": "HC112",
"results": 400,
"counts": { "pass": 210, "fail": 190, "needs_review": 0, "not_evaluated": 0 },
"affected": 190,
"top": [
{ "step": "eshop", "locale": "pl", "check": "HC112", "page": "sklep-kubek", "path": "/pl/sklep/kubek", "url": "https://www.example.com/pl/sklep/kubek", "verdict": "fail", "evidence": "no JSON-LD block on the page" }
]
}
]
}
idof a group is made of its values, so the same group has the same id every week: use it as the key in your dashboard.affectedisfailplusneeds_review.checksnames every check of the run with its text, pack and level (errororwarningwhen it fails).diffis the summary of the diff below;previousisnullfor the first run of a scenario in an environment.
Diff
GET …/health/diff compares the results that fail or are unsure with what the scenario had open after its previous shared run in the same environment and project. Runs of the same scenario in another project are never compared.
A result is fixed only when this run checked it and it passed. A result this run did not check stays open and is listed as unchecked: a page outside this week's rotating sample (rotate), a language left out, a check the evaluator could not decide. It keeps its first_seen, and the next run that checks it decides. A result that goes 8 runs in a row or 60 days without a check is dropped: it is listed once more with "expired": true and counted in expired.
| Parameter | Meaning |
|---|---|
state | new, fixed, still_open or unchecked; without it, all four lists |
locale, step, check, pack | Only results with this value |
limit, offset | Paging within each list: up to 2000 (default 200) |
{
"schema": "kaloko.health-diff.v1",
"run": { "id": "2026-10-12-seo-weekly-a1b2c3", "…": "…" },
"previous": { "id": "2026-10-05-seo-weekly-d4e5f6", "started_at": "2026-10-05T05:00:00.000Z" },
"counts": { "new": 14, "fixed": 3, "still_open": 859, "unchecked": 0, "worse": 1, "expired": 0 },
"open": 876,
"truncated": false,
"new": {
"total": 14,
"items": [
{ "id": "eshop|pl|HC112|sklep-kubek", "step": "eshop", "locale": "pl", "check": "HC112", "page": "sklep-kubek", "url": "https://www.example.com/pl/sklep/kubek", "severity": "warning", "text": "The page carries structured data (JSON-LD)", "first_seen": { "run": "2026-10-12-seo-weekly-a1b2c3", "at": "2026-10-12T05:00:00.000Z" } }
]
},
"fixed": { "total": 3, "items": [] },
"still_open": { "total": 859, "items": [] },
"unchecked": { "total": 0, "items": [] }
}
idof a result isstep|locale|check|page. It stays the same while the step, language, check and page keep their ids, so you can follow one page across weeks.pageisnullfor a plain step.severityiserrororwarningfor a failing check andinfowhen the evaluator was unsure. A still open result whose severity changed haswaswith the earlier one;worsecounts those that got worse.first_seenis the run where the result started failing and has not passed in any run since. A result that was fixed and came back starts again.opencounts what is open after this run: failing or unsure now, plus unchecked.- A site with more than 50,000 open results in one run keeps the worst 50,000 and says
truncated: true; the rest count as unchecked, never as fixed.
Findings
Eight hundred failing pages are usually a dozen problems: one template in one language misses its structured data. GET /api/v1/orgs/<org>/scenarios/<id>/findings groups what the scenario has open into findings: one check on one site in one language on one step. The fingerprint is check|site|locale|step, where the site is the origin of the page's URL (https://www.example.com). It stays the same from week to week, so a finding is counted, decided and tracked once, however many pages it hits. The read:health token reads findings too (MCP list_findings).
| Parameter | Meaning |
|---|---|
environment | The environment; without it, the newest one with recorded health |
locale, step, check | Only findings with this value |
status | open, acknowledged, ignored or fixed |
limit, offset | Paging: up to 1000 (default 200) |
{
"schema": "kaloko.health-findings.v1",
"scenario": "seo-weekly", "project": "web", "environment": "production",
"run": { "id": "2026-10-12-seo-weekly-a1b2c3", "started_at": "2026-10-12T05:00:00.000Z", "canvas": "…" },
"page": "https://kaloko.app/acme/health/seo-weekly?environment=production",
"counts": { "open": 9, "acknowledged": 2, "ignored": 1, "fixed": 3 },
"filter": {}, "total": 15, "offset": 0, "limit": 200,
"findings": [
{
"id": "5f0c2a9e1b7d4c33",
"fingerprint": "HC112|https://www.example.com|pl|eshop",
"check": "HC112", "text": "The page carries structured data (JSON-LD)", "pack": "seo",
"site": "https://www.example.com", "locale": "pl", "step": "eshop",
"severity": "warning", "status": "acknowledged", "reason": null,
"status_by": "jana@example.com", "status_at": "2026-10-12T09:14:00.000Z",
"count": 190, "unchecked": 0, "fixed": 4,
"samples": [
{ "page": "sklep-kubek", "url": "https://www.example.com/pl/sklep/kubek", "edit_url": "https://cms.example.com/pages/812/edit" }
],
"first_seen": { "run": "2026-09-28-seo-weekly-77aa01", "at": "2026-09-28T05:00:00.000Z" },
"last_seen": { "run": "2026-10-12-seo-weekly-a1b2c3", "at": "2026-10-12T05:00:00.000Z" },
"issue": { "tracker": "jira", "key": "WEB-412", "url": "https://acme.atlassian.net/browse/WEB-412", "state": "open" }
}
]
}
idis a short hash of the fingerprint; use it in links and inPATCH.severityis the worst of the finding's results;countis the pages it affects now.uncheckedcounts pages the newest run did not check (they stay open),fixedthe pages the newest run fixed.sampleslists up to 10 pages with theedit_urltheir stack item names, so a content team goes straight to the CMS (Find what fails on a site).first_seenis the earliest first seen of its results.last_seenis the newest run that checked it and still saw it fail; for a fixed finding it is the run before the fix.statusisfixedonce none of its pages fails; otherwise what a person set (acknowledged,ignoredwith areason) oropen. A decision stays with the fingerprint: an ignored finding that comes back is still ignored.- With
traffic:on the stack (Fix the pages people actually see first), a finding hastraffic(clicksandimpressionsadded up over its pages that have numbers, and how manypagesthose are) andimpact, and each sample its owntraffic. Without traffic data neither key is there. issue.keyisWEB-412in Jira or Linear,acme/website#87in GitHub andMKT-12in Plane.- Findings are worst first, the fixed ones last.
To acknowledge a finding or ignore it, send PATCH …/scenarios/<id>/findings/<finding>[?environment=] with { "status": "acknowledged" }, { "status": "ignored", "reason": "Old blog, moving to a new CMS in November" } or { "status": "open" }. Anyone who may comment on the scenario's runs may do it; a token needs the comment scope (a read:health token never changes anything). The app shows the same table on Health → Findings of each scenario, with buttons for the same three choices.
Issues for findings
A scenario can open an issue for each new finding in Jira, Linear, GitHub Issues or Plane. A Developer / Tester switches it on with PUT …/scenarios/<id>/findings/sync:
{ "tracker": "jira", "min_severity": "error", "environment": "production" }
In Jira and Linear the issue goes to the project or team the scenario's project maps to in Settings → Integrations (Connect trackers and channels). GitHub and Plane take the destination in the setting itself, and routes send some findings to another tracker than the scenario's:
{
"tracker": "github", "min_severity": "warning",
"github": { "repository": "acme/website", "labels": ["seo"], "assignee": "jana" },
"plane": { "project": "MKT", "labels": ["content"] },
"routes": [{ "tracker": "plane", "checks": ["HC127", "HC9*"], "packs": ["aeo"] }]
}
github: the repository (owner/repo), labels and an optional assignee. Kaloko opens the issue as the Kaloko GitHub app when the app is installed on the repository and has the Issues permission, otherwise with the fine-grained token an admin connected (Issues: read and write on that repository).plane: the project identifier (MKT) and labels that already exist in the project.- The repository and the Plane project must be on the list an organization admin allowed for the scenario's project in Settings → Integrations (a project without its own row uses the default row). Anything else is refused with 403 before GitHub or Plane is asked, so the answer says nothing about whether it exists. When an admin takes a destination off the list, no new issues go there; the ones that exist are still followed.
routes: at most 20, in order. The first route that names the finding's check (HC127, or a prefix such asHC1*) or its pack (seo,aeo, …) decides; every other finding goes totracker. Each tracker a route names must be connected. When the routes change, an issue that exists stays where it is and is followed there.
Saving checks the repository, the assignee, the project and the labels with the tracker and says what is wrong.
After each shared run of the scenario Kaloko creates one issue per new finding at or above min_severity (error, warning or info), never two for one fingerprint and none for an ignored one. The issue says which check fails where, how many pages, up to ten of them with their edit links and, with traffic:, the clicks and impressions of each page and of the whole finding with its impact; it links back to the finding. When the number of affected pages changes by at least three and a quarter, the issue gets a comment; when the finding is fixed, a comment and the issue is closed (Jira: the first transition into Done; Linear: the team's first completed state; GitHub: closed as completed; Plane: the project's first completed state). If it comes back, the same issue gets a comment and is opened again where the tracker allows it (Plane: the first unstarted state).
A run creates at most 20 issues, the worst first, and makes at most 60 calls to the trackers within 20 seconds, of them at most 25 requests to Plane, each counted (its API takes 60 a minute; closing an issue also reads the project's states once per run); the rest follow with the next run. A finding the tracker refuses (a field it does not accept) keeps the error in the list and the others go on. When a tracker refuses the connection, asks Kaloko to slow down or does not answer, the run stops for that tracker and the next run tries again; findings routed to another tracker go on. A create that never reached the tracker (a connection that could not be renewed, a Linear team that is not there, a Plane address that is refused) lets the finding try again with the next run. If a tracker does not say clearly whether it created an issue (a timeout or a server error), the finding shows the issue as being created, with the reason in issue.error, and Kaloko does not open another one: check the tracker, and if nothing is there, choose Try again at the finding on the findings page or send POST …/scenarios/<id>/findings/<finding>/retry[?environment=] (Developer / Tester; once the issue has waited two minutes, so a create still on its way is never cut off); the next run creates it. Saving the setting also lets go of such claims older than an hour. A scenario whose trackers take no new issues (a destination taken off the list, a mapping removed) still comments on, closes and reopens the issues it opened.
The setting belongs to the scenario in its project: moved to another project, the scenario stops opening issues until someone switches it on there. { "tracker": null } switches it off; GET on the same address shows the setting and the trackers the organization can sync to.
Runs shared before
The counts of a run are made once, after it is shared. A run shared before this API existed is counted on each request instead, which can take a few seconds for a large run; its diff compares it with the run before it and says "recorded": false. The first run shared after that starts the history of its scenario.
When something changes
The health.changed webhook sends the diff's counts and the first new and fixed results after every shared run where something moved: Webhooks.