API kondice pro dashboardy
Týdenní SEO průchod několika tisíci stránek skončí jako jeden běh se stovkami nálezů. Dashboard ho nechce stahovat a počítat znovu. Tyto adresy odpovídají už sečtenými čísly: po jazycích, krocích (krok stack je jedna šablona stránek), kontrolách nebo packech, se stránkami, kterých se problém týká nejvíc, a s tím, co se změnilo od běhu předtím.
Token pro dashboard
V Nastavení → API tokeny vytvořte token s rozsahem read:health (na Enterprise i jako servisní účet). Čte adresy z této stránky a zbytek kondice (GET …/health běhu, scénáře nebo projektu, MCP get_health); na všechno ostatní odpoví 403. Poslouží i token s rozsahem read.
curl -H "Authorization: Bearer $KALOKO_TOKEN" \
"https://kaloko.app/api/v1/orgs/acme/scenarios/seo-weekly/latest/health/aggregate?by=locale,step"
Adresy
| Požadavek | Co vrátí |
|---|---|
GET /api/v1/orgs/<org>/scenarios/<id>/latest | Nejnovější sdílený běh scénáře, který vidíte: id, datum, verdikt, počty kondice a odkazy níže. ?environment=production vybere nejnovější běh v jednom prostředí |
GET …/scenarios/<id>/latest/health/aggregate | Souhrn tohoto běhu jedním voláním |
GET …/scenarios/<id>/latest/health/diff | Rozdíl tohoto běhu jedním voláním |
GET /api/v1/orgs/<org>/runs/<run>/health/aggregate | Počty po skupinách s nejvíc zasaženými stránkami a počty z rozdílu |
GET /api/v1/orgs/<org>/runs/<run>/health/diff | Nové, opravené a pořád otevřené výsledky, každý s během, který ho viděl poprvé |
GET /api/v1/orgs/<org>/scenarios/<id>/findings | Otevřené výsledky seskupené do nálezů podle kontroly, webu, jazyka a kroku, se stavem (níže) |
MCP má totéž jako get_health_aggregate, get_health_diff (s run_id, nebo se scenario a environment) a list_findings.
Co se počítá
Jeden výsledek je jedna stránka v jednom jazyce pro jednu kontrolu. Stránka prošlá ve více viewportech se počítá jednou, s nejhorším verdiktem. Krok stack počítá každou svou stránku, obyčejný krok je stránkou sám. Výsledek je pass, fail, needs_review (hodnotitel si nebyl jistý) nebo not_evaluated. Kontroly, které se na stránku nevztahují, se nepočítají.
Kondice jen radí: tato čísla nikdy nezmění verdikt kroku ani běhu.
Souhrn
GET …/health/aggregate bere:
| Parametr | Význam |
|---|---|
by | Čárkami oddělené: locale, step, check, pack. Výchozí locale,step,check. Prázdné sečte vše do jedné skupiny |
locale, step, check, pack | Jen výsledky s touto hodnotou |
top | Zasažené stránky na skupinu, 0 až 20 (výchozí 5); selhávající stránky před nejistými |
limit | Skupiny v odpovědi, 1 až 5000 (výchozí 500), nejvíc selhávající první |
{
"schema": "kaloko.health-aggregate.v1",
"run": { "id": "2026-10-12-seo-weekly-a1b2c3", "scenario": "seo-weekly", "title": "Týdenní 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" }
]
}
]
}
idskupiny se skládá z jejích hodnot, takže stejná skupina má každý týden stejné id: použijte ho jako klíč v dashboardu.affectedjefailplusneeds_review.checksvyjmenuje každou kontrolu běhu s textem, packem a úrovní (errornebowarning, když selže).diffje shrnutí rozdílu níže;previousjenullu prvního běhu scénáře v daném prostředí.
Rozdíl
GET …/health/diff porovná výsledky, které selhávají nebo jsou nejisté, s tím, co měl scénář otevřené po svém předchozím sdíleném běhu ve stejném prostředí a projektu. Běhy stejného scénáře v jiném projektu se nikdy neporovnávají.
Výsledek je opravený (fixed), jen když ho tento běh zkontroloval a prošel. Výsledek, který tento běh nezkontroloval, zůstává otevřený a je v seznamu nezkontrolované (unchecked): stránka mimo tento týdenní výběr (rotate), vynechaný jazyk, kontrola, o které hodnotitel nedokázal rozhodnout. Drží si first_seen a rozhodne další běh, který ho zkontroluje. Výsledek, který 8 běhů po sobě nebo 60 dní nikdo nezkontroloval, vypadne: naposledy se objeví s "expired": true a započítá se do expired.
| Parametr | Význam |
|---|---|
state | new, fixed, still_open nebo unchecked; bez něj všechny čtyři seznamy |
locale, step, check, pack | Jen výsledky s touto hodnotou |
limit, offset | Stránkování v každém seznamu: nejvýš 2000 (výchozí 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": [] }
}
idvýsledku jestep|locale|check|page. Zůstává stejné, dokud krok, jazyk, kontrola a stránka drží svá id, takže jednu stránku sledujete týden po týdnu. U obyčejného kroku jepagenull.severityjeerrornebowarningu selhávající kontroly ainfo, když si hodnotitel nebyl jistý. Pořád otevřený výsledek, kterému se závažnost změnila, má vewastu předchozí;worsepočítá ty, které se zhoršily.first_seenje běh, ve kterém výsledek začal selhávat a od té doby v žádném běhu neprošel. Výsledek, který byl opravený a vrátil se, začíná znovu.openpočítá, co je po tomto běhu otevřené: co teď selhává nebo je nejisté, plus nezkontrolované.- Web s víc než 50 000 otevřenými výsledky v jednom běhu si nechá 50 000 nejhorších a řekne
truncated: true; zbytek se počítá jako nezkontrolovaný, nikdy jako opravený.
Nálezy
Osm set selhávajících stránek bývá tucet problémů: jedné šabloně v jednom jazyce chybí strukturovaná data. GET /api/v1/orgs/<org>/scenarios/<id>/findings seskupí, co má scénář otevřené, do nálezů: jedna kontrola na jednom webu v jednom jazyce na jednom kroku. Otisk (fingerprint) je check|site|locale|step, kde web je origin URL stránky (https://www.example.com). Týden po týdnu zůstává stejný, takže nález se počítá, rozhoduje a sleduje jednou, ať zasáhne kolik chce stránek. Nálezy čte i token read:health (MCP list_findings).
| Parametr | Význam |
|---|---|
environment | Prostředí; bez něj nejnovější se zaznamenanou kondicí |
locale, step, check | Jen nálezy s touto hodnotou |
status | open, acknowledged, ignored nebo fixed |
limit, offset | Stránkování: nejvýš 1000 (výchozí 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" }
}
]
}
idje krátký hash otisku; používejte ho v odkazech a vPATCH.severityje nejhorší z výsledků nálezu;countje počet stránek, kterých se teď týká.uncheckedpočítá stránky, které nejnovější běh nezkontroloval (zůstávají otevřené),fixedstránky, které nejnovější běh opravil.samplesukáže až 10 stránek sedit_url, které uvádí jejich položka stacku, takže obsahový tým jde rovnou do CMS (Najděte, co na webu selhává).first_seenje nejstarší první výskyt z jeho výsledků.last_seenje nejnovější běh, který ho zkontroloval a pořád selhával; u opraveného nálezu je to běh před opravou.statusjefixed, jakmile žádná jeho stránka neselhává; jinak to, co nastavil člověk (acknowledged,ignoreds důvodem vreason), neboopen. Rozhodnutí patří k otisku: ignorovaný nález, který se vrátí, zůstává ignorovaný.- Když má stack
traffic:(Opravte nejdřív stránky, které lidé opravdu vidí), má náleztraffic(clicksaimpressionssečtené přes jeho stránky, které čísla mají, a kolik těch stránek je,pages) aimpacta každá ukázková stránka svojetraffic. Bez dat o návštěvnosti tam žádný z klíčů není. issue.keyjeWEB-412v Jiře nebo Linearu,acme/website#87na GitHubu aMKT-12v Plane.- Nálezy jdou od nejhoršího, opravené na konci.
Nález potvrdíte nebo ignorujete přes PATCH …/scenarios/<id>/findings/<nález>[?environment=] s { "status": "acknowledged" }, { "status": "ignored", "reason": "Starý blog, v listopadu se stěhuje do nového CMS" } nebo { "status": "open" }. Smí to každý, kdo smí komentovat běhy scénáře; token potřebuje rozsah comment (token read:health nic nemění). Stejnou tabulku ukazuje aplikace v Kondice → Nálezy u každého scénáře, s tlačítky pro tytéž tři možnosti.
Issues k nálezům
Scénář může pro každý nový nález založit issue v Jiře, Linearu, GitHub Issues nebo Plane. Zapíná to Developer / Tester přes PUT …/scenarios/<id>/findings/sync:
{ "tracker": "jira", "min_severity": "error", "environment": "production" }
V Jiře a Linearu jde issue do projektu nebo týmu, na který je projekt scénáře namapovaný v Nastavení → Integrace (Propojte trackery a kanály). U GitHubu a Plane je cíl přímo v nastavení a routes pošlou část nálezů do jiného trackeru než zbytek scénáře:
{
"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: repozitář (owner/repo), štítky a volitelně komu issue přiřadit. Kaloko issue založí jako aplikace Kaloko na GitHubu, když je na repozitáři nainstalovaná a má oprávnění Issues; jinak fine-grained tokenem, který připojil admin (Issues: read and write na ten repozitář).plane: identifikátor projektu (MKT) a štítky, které v projektu už existují.- Repozitář i projekt v Plane musí být na seznamu, který pro projekt scénáře povolil admin organizace v Nastavení → Integrace (projekt bez vlastního řádku použije výchozí). Cokoli jiného Kaloko odmítne s 403 dřív, než se zeptá GitHubu nebo Plane, takže odpověď neprozradí, jestli to existuje. Když admin cíl ze seznamu odebere, nová issues tam už nepůjdou; ta existující Kaloko sleduje dál.
routes: nejvýš 20, v pořadí. Rozhodne první cesta, která jmenuje kontrolu nálezu (HC127, nebo začátek jakoHC1*) nebo jeho balíček (seo,aeo…); všechny ostatní nálezy jdou dotracker. Každý tracker z cest musí být připojený. Když se cesty změní, existující issue zůstane, kde je, a Kaloko ho sleduje tam.
Při uložení Kaloko u trackeru ověří repozitář, přiřazeného člověka, projekt i štítky a řekne, co nesedí.
Po každém sdíleném běhu scénáře Kaloko založí jedno issue na každý nový nález se závažností aspoň min_severity (error, warning nebo info), nikdy dvě pro jeden otisk a žádné pro ignorovaný. Issue říká, která kontrola kde selhává, na kolika stránkách, ukáže až deset z nich s odkazy na úpravu a s traffic: i kliknutí a zobrazení každé stránky a celého nálezu s jeho dopadem; odkazuje zpět na nález. Když se počet zasažených stránek změní aspoň o tři a o čtvrtinu, issue dostane komentář; když je nález opravený, komentář a issue se zavře (Jira: první přechod do Done; Linear: první dokončený stav týmu; GitHub: zavřené jako dokončené; Plane: první dokončený stav projektu). Když se vrátí, totéž issue dostane komentář a znovu se otevře, pokud to tracker dovolí (Plane: první stav k zahájení).
Jeden běh založí nejvýš 20 issues, nejhorší první, a do trackerů zavolá nejvýš 60krát během 20 sekund, z toho nejvýš 25 požadavků do Plane, počítá se každý (jeho API bere 60 za minutu; zavření issue navíc jednou za běh načte stavy projektu); zbytek přijde s dalším během. Nález, který tracker odmítne (třeba kvůli poli, které nebere), si chybu nechá v seznamu a ostatní pokračují. Když tracker odmítne spojení, chce zpomalit nebo neodpovídá, běh pro ten tracker skončí a zkusí to další běh; nálezy pro jiný tracker pokračují. Založení, které se do trackeru vůbec nedostalo (spojení nešlo obnovit, tým v Linearu neexistuje, adresa Plane je odmítnutá), zkusí nález znovu s dalším během. Když tracker jasně neřekne, jestli issue založil (vypršel čas nebo chyba serveru), nález ukazuje issue jako zakládané s důvodem v issue.error a Kaloko druhé nezaloží: podívejte se do trackeru, a když tam nic není, zvolte u nálezu na stránce nálezů Zkusit znovu (jde to, až issue čeká dvě minuty), nebo pošlete POST …/scenarios/<id>/findings/<finding>/retry[?environment=] (Developer / Tester); další běh ho založí. Zakládání visící déle než hodinu uvolní i uložení nastavení.
Nastavení patří ke scénáři v jeho projektu: když scénář přesunete do jiného projektu, issues přestane zakládat, dokud je tam někdo nezapne. { "tracker": null } synchronizaci vypne; GET na stejné adrese ukáže nastavení a trackery, do kterých organizace může nálezy posílat.
Běhy sdílené dřív
Počty běhu vzniknou jednou, po jeho sdílení. Běh sdílený dřív, než toto API existovalo, se spočítá při každém dotazu, což u velkého běhu může pár sekund trvat; jeho rozdíl ho porovná s během před ním a řekne "recorded": false. První běh sdílený potom začne historii svého scénáře.
Když se něco změní
Webhook health.changed pošle počty z rozdílu a první nové a opravené výsledky po každém sdíleném běhu, ve kterém se něco pohnulo: Webhooky.