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

RequestWhat it answers
GET /api/v1/orgs/<org>/scenarios/<id>/latestThe 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/aggregateThe aggregate of that run, in one call
GET …/scenarios/<id>/latest/health/diffThe diff of that run, in one call
GET /api/v1/orgs/<org>/runs/<run>/health/aggregateCounts per group with the most affected pages, and the diff's counts
GET /api/v1/orgs/<org>/runs/<run>/health/diffNew, fixed and still open results, each with the run that first saw it
GET /api/v1/orgs/<org>/scenarios/<id>/findingsOpen 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:

ParameterMeaning
byComma-separated: locale, step, check, pack. Default locale,step,check. Empty groups everything into one
locale, step, check, packOnly results with this value
topAffected pages per group, 0 to 20 (default 5); failing pages come before unsure ones
limitGroups 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" }
      ]
    }
  ]
}

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.

ParameterMeaning
statenew, fixed, still_open or unchecked; without it, all four lists
locale, step, check, packOnly results with this value
limit, offsetPaging 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": [] }
}

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).

ParameterMeaning
environmentThe environment; without it, the newest one with recorded health
locale, step, checkOnly findings with this value
statusopen, acknowledged, ignored or fixed
limit, offsetPaging: 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" }
    }
  ]
}

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"] }]
}

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.

Kaloko · latest · 2026-11-21