Docs

Kaloko

Download
Markdown with pictures (.zip)Docusaurus folder (.zip)VitePress folder (.zip)MkDocs folder (.zip)Offline HTML (.zip)PDFChangelog as JSON
Pages

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" }
      ]
    }
  ]
}
  • id of 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.
  • affected is fail plus needs_review.
  • checks names every check of the run with its text, pack and level (error or warning when it fails).
  • diff is the summary of the diff below; previous is null for 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.

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": [] }
}
  • id of a result is step|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. page is null for a plain step.
  • severity is error or warning for a failing check and info when the evaluator was unsure. A still open result whose severity changed has was with the earlier one; worse counts those that got worse.
  • first_seen is 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.
  • open counts 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).

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" }
    }
  ]
}
  • id is a short hash of the fingerprint; use it in links and in PATCH.
  • severity is the worst of the finding's results; count is the pages it affects now. unchecked counts pages the newest run did not check (they stay open), fixed the pages the newest run fixed.
  • samples lists up to 10 pages with the edit_url their stack item names, so a content team goes straight to the CMS (Find what fails on a site).
  • first_seen is the earliest first seen of its results. last_seen is the newest run that checked it and still saw it fail; for a fixed finding it is the run before the fix.
  • status is fixed once none of its pages fails; otherwise what a person set (acknowledged, ignored with a reason) or open. 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 has traffic (clicks and impressions added up over its pages that have numbers, and how many pages those are) and impact, and each sample its own traffic. Without traffic data neither key is there.
  • issue.key is WEB-412 in Jira or Linear, acme/website#87 in GitHub and MKT-12 in 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 as HC1*) or its pack (seo, aeo, …) decides; every other finding goes to tracker. 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.

On this pageOn this page