Docs

Kaloko

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

Monitor SEO and answer engines every week

A translation release goes out on Thursday. On Monday someone notices that the Polish product pages lost their structured data and half of the Greek magazine has no meta description. A weekly walk of every public page would have said so on Friday morning. This page sets one up, with Squared as the example: www.squared.one in 20 languages and www.vyvolej.to in Czech, Slovak and Ukrainian, about 400 pages per language.

The plan:

  • one stack step per content family (e-shop, magazine, FAQ, the rest), each reading the pages from the site's per-language sitemaps;
  • lanes for the content families, so the canvas shows one row per family;
  • sessions for the kinds of visitors whose pages you check (a visitor from search, a signed-in club member);
  • the seo and aeo packs on every page, advisory, never part of a verdict;
  • a GitHub Actions workflow that walks it every week and shares the run;
  • the results read back through the API or MCP for a dashboard.

1. Find the sitemaps

The quick way is to let Kaloko draft steps 1 and 2 from the site itself:

npx kaloko init --seo https://www.squared.one

It reads robots.txt, takes the languages from the sitemap addresses (or from the first path segment of the pages when the site has one sitemap), samples each language's pages and writes qa/flows/seo-squared-one.yml: one rotating stack step per content family with a match for every language, the seo and aeo packs, and the production environment in a new kaloko.config.yml. Families are paired across languages by the sitemaps' hreflang links, then by the same segment, then by size. The comment at the top of the file lists the pairs it guessed by size; check those before the first walk. --families 6 takes more families, --limit 100 more pages a week, --packs seo,aeo,a11y adds accessibility. When the site cannot be reached, nothing is written. The rest of this page explains what the draft contains, so you can sharpen it.

Squared lists one gzipped sitemap per language in robots.txt:

Sitemap: https://www.squared.one/sitemaps/en_US/sitemap.xml.gz
Sitemap: https://www.squared.one/sitemaps/de/sitemap.xml.gz
Sitemap: https://www.squared.one/sitemaps/es/sitemap.xml.gz
…

items: { robots: true } reads those lines. When a sitemap's address names the walked language as a segment (/sitemaps/de/…), only that language's sitemaps are read, so the German walk gets the German pages. en_US finds en_us or en-us; en does not pick en-us. A site with one sitemap for all languages gets all of it, and match picks the language. You can also name the file yourself: sitemap: '/sitemaps/{locale}/sitemap.xml.gz'. Gzipped sitemaps and sitemap indexes work either way.

A staging behind a password works too. kaloko walk reads robots.txt and the sitemaps with the environment's access (its headers, HTTP Basic, client certificates and the walk's cookies), on the environment's own addresses only. A sitemap on another host, a CDN for example, or one that redirects there is read without them. Each file has 60 seconds and 60 MB.

2. Split the pages into content families

Each family is a stack step with its own match or exclude. Look at the first path segment of each language's sitemap first: on Squared even the e-shop is translated (/fi/tuotteet/, /pl/sklep/, /bg/foto-produkti/), and the magazine is /de/zeitschrift/, /es/revista/, /fi/lehti/. One regex with every translation keeps one step per family for all languages:

schema: qawalk.scenario.v1
id: SEO-weekly-squared
title: Weekly SEO and answer-engine monitor (squared.one)
kind: flow
locales: [en_US, de, es, fr, it, nl, pt]
viewports: { desktop: [1280, 800] }
environments: [production]
readonly: true
page: landing
health: { site: true }
lanes: [E-shop, Magazine, FAQ, Club and other pages]
sessions:
  visitor: { title: Visitor from search }
nodes:
  - id: eshop
    kind: stack
    title: E-shop
    lane: 0
    session: visitor
    packs: [seo, aeo, locale]
    items:
      robots: true
      match: '^/([a-z]{2}/)?(eshop|tuotteet|sklep|trgovina|katastima|pood|veikals|parduotuve|webshop|produse|foto-produkti)/'
      limit: 400
    fields:
      - { id: title, from: title }
      - { id: http, from: http }
      - { id: jsonld_types, label: Structured data }
      - { id: og_title, label: OG title, from: og:title }
      - { id: canonical, from: canonical }
    criteria:
      - { id: AC1, text: Product pages carry Product and BreadcrumbList data, check: { type: deterministic, assert: jsonld_present, types: [Product, BreadcrumbList] } }
  - id: magazine
    kind: stack
    title: Magazine
    lane: 1
    session: visitor
    packs: [seo, aeo, locale]
    items:
      robots: true
      match: '^/([a-z]{2}/)?(magazine|zeitschrift|revista|rivista|lehti|magazyn|revija|magazin|periodiko|ajakiri|zurnals|zurnalas|spisanie)/'
    fields: [{ id: title, from: title }, { id: words, from: words }, { id: jsonld_types }]
  - id: faq
    kind: stack
    title: FAQ
    lane: 2
    session: visitor
    packs: [seo, aeo, locale]
    items: { robots: true, match: '^/([a-z]{2}/)?faq/' }
    fields: [{ id: title, from: title }, { id: jsonld_types }]
  - id: pages
    kind: stack
    title: Club and other pages
    lane: 3
    session: visitor
    packs: [seo, aeo, locale]
    items: { robots: true, exclude: '/(eshop|tuotteet|sklep|trgovina|katastima|pood|veikals|parduotuve|webshop|produse|foto-produkti|magazine|zeitschrift|revista|rivista|lehti|magazyn|revija|magazin|periodiko|ajakiri|zurnals|zurnalas|spisanie|faq)(/|$)' }
    fields: [{ id: title, from: title }, { id: jsonld_types }]
edges: []

Quote a source that contains {locale} inside { … }, or YAML reads the braces as a map.

When one regex with every translation gets too long, give match (or exclude) one regex per language. Kaloko tries the walked locale, then its language (en for en_US), then default:

    items:
      robots: true
      match:
        default: '^/([a-z]{2}/)?eshop/'
        fi: '^/fi/tuotteet/'
        pl: '^/pl/sklep/'
        bg: '^/bg/foto-produkti/'

A match map without the walked locale and without default stops the walk with an error, so a forgotten language never takes every page of the site. An exclude map without the locale drops nothing.

match and exclude always apply before limit, for every source. When the pages come from your own script (items: { script: steps/seo-items.mjs }), one script can serve every family: it gets node (id, title, lane, lane_title, session) and items.params:

    items: { script: steps/seo-items.mjs, params: { family: magazine } }
// steps/seo-items.mjs
export default async ({ locale, node, params, url }) => {
  const res = await fetch(url(`/api/sitemap/${params.family}?locale=${locale}`))
  return (await res.json()).map((p) => ({ path: p.path, title: p.title }))
}

Before the first full walk, check the counts with npx kaloko walk --limit 3 and look at the numbers per step. A step with 0 pages usually means a translated segment is missing from its regex.

One page in all its languages

By default each language reads its own list, so the Czech product /eshop/obaly-na-fotky/ and its Slovak translation /sk/eshop/obaly-na-fotky-nahodna-farba/ are two pages of the stack, and each language samples different products. To see the translations as language versions of one page, let the stack take its list in one language and follow each page's hreflang to the others:

    items:
      robots: true
      match: '^/eshop/'
      variants: hreflang
      source_locale: cs
      limit: 100
      rotate: week

The list, match, limit and rotate come from source_locale (by default the scenario's first locale). In every other language Kaloko reads each chosen page and walks the address its <link rel="alternate" hreflang> gives for that language, or the Link header, or the sitemap's xhtml:link when the page names none. The page keeps the id of the source page, so the stack index has one row per product with a screenshot in every language, and every language checks the same products in a given week. The row shows the source page's address, title and fields when the run walks the source language too; a run of other languages only (--locales sk) shows what the first walked language found.

A page without a version in a language does not disappear quietly. The stack index marks it with that language, and HC1005 counts it: there is no hreflang for the language, the page lists only x-default (which is no translation), the hreflang for the language points back to the page itself, the page cannot be read, or the translation answers an error (error 404). Pages whose Slovak hreflang all lead to one address (usually a listing or the home page) count too. kaloko export findings lists each of them as a row of that language at the source page, where the hreflang belongs. Whether the translation links back is HC125 of the seo pack.

Kaloko reads the HTML as the server sends it, without running scripts, with the environment's access (its headers and HTTP Basic, client certificates, the walk's cookies) on the environment's own addresses only. When none of the alternates is on the host the page was read from, the page names another site's addresses: staging or a preview whose hreflang names production, also with one domain per language. Kaloko then opens each alternate's path on the walked language's address from the environment.

When your own script lists the pages per language instead, give each page a key that is the same in every language (for example the path of the source page). Pages with one key are one page of the stack.

Hosted runs (kaloko schedule add) group language versions the same way, with the same pages in the same week. Reading a source page for its hreflang counts as a page of the monthly budget there; see Hosted runs.

3. Choose the sessions

A session is one kind of visitor; every step names one. For a public SEO monitor one is enough: visitor, signed out, the way a search engine sees the site. When signed-in pages matter (the club area for members), add a session with an account, save its sign-in once with npx kaloko auth save --env production --account member, and give those steps session: member. Keep signed-in steps out of the sitemaps step: search engines never see them.

4. What the packs check

The seo pack checks title, description, canonical, hreflang, Open Graph, robots, the H1 and the viewport, and now also that JSON-LD is on the page (HC112) and that every block is valid JSON (HC113). The aeo pack adds cheap signals for AI search and assistants: FAQPage or QAPage data where the page asks and answers (HC901), a short answer-first paragraph under the H1 (HC902), /llms.txt at the site root, fetched once per walk (HC903), a meta description (HC904), and the page as GPTBot gets it without JavaScript (HC905): one more request per page, without cookies, only where robots.txt lets GPTBot in. It fails when the title, canonical, H1, JSON-LD or most of the text appear only after scripts run; a site or WAF that turns GPTBot away shows as not evaluated, not as a failure. To check another crawler, write the criterion yourself with assert: nojs_parity and user_agent: claudebot (or googlebot, perplexitybot, a whole user agent string). Every check is advisory. Leave the errors pack out of these steps: it is for error pages, and on normal pages its soft-404 and explanation checks (HC601, HC605) stay not applicable. When the team decides that product pages must carry their structured data, adopt the check or write your own criterion, as AC1 above does. The details are in Criteria, checks and packs.

What one page cannot show, the stack as a whole can. After the walk the seo pack compares the pages of one language with each other: shared titles, descriptions and H1s (HC121–HC123), canonicals that point elsewhere (HC124), hreflang the other language version does not answer (HC125), and sitemap pages that redirect, answer an error or say noindex (HC126). The findings count pages, and items.json lists the addresses, so they can go to whoever fixes them in groups.

The locale pack watches the language versions: html lang, the page's own hreflang, the language of the text (an untranslated page in a language version) and the decimal separator of prices (12,50 € in German, $12.50 in English), always against the walked locale.

health: { site: true } adds the checks of the whole site, once per run: robots.txt (typos, blocked start pages, blocked AI crawlers), the sitemaps robots.txt lists (reachable, valid, absolute same-host addresses, sane lastmod), /llms.txt, and http:// to https:// and the other host name (with or without www) in one redirect. When the site blocks AI crawlers on purpose, set health: { site: { ai_crawlers: false } }. kaloko health gives the site checks a line per site.

5. Size the walk

Each page takes about 1–2 seconds and stores about four files, and a shared run holds at most 20,000 files. Squared has about 400 pages per language, so seven languages (2,800 pages, about 11,000 files) fit into one run. Split the languages into scenario files that share the same steps:

FileLanguages
qa/flows/seo-squared-west.ymlen_US, de, es, fr, it, nl, pt
qa/flows/seo-squared-north-east.ymlda, sv, fi, pl, sl, hr, el
qa/flows/seo-squared-baltic-south.ymlet, lv, lt, hu, ro, bg
qa/flows/seo-vyvolej.ymlcs, sk, uk (environment with base_url: https://www.vyvolej.to)

walk.concurrency in kaloko.config.yml walks several languages at once; 3 or 4 keeps a weekly run of a few thousand pages within an hour or two.

Cover a big catalogue in turns

When every language together has more pages than one run can hold, walk a part of each family every week. rotate: week takes limit pages starting at a different place each ISO week, so the whole list is covered after pages ÷ limit weeks:

    items: { robots: true, match: '^/([a-z]{2}/)?eshop/', limit: 100, rotate: week }

With 400 product pages per language this covers the e-shop every four weeks at a quarter of the cost. The walk says which part it takes (rotating sample, week 2026-W41 — pages 101…200 of 400, all covered in 4 weeks). The same week gives the same pages, so a run you repeat on Tuesday checks what Monday checked.

rotate: run counts runs instead of weeks. Kaloko keeps the count and the time each page was last checked in .cache/stack/ of the output folder (tmp/kaloko), so it works where that folder stays between runs (your laptop, a self-hosted runner). A fresh GitHub Actions checkout starts from zero every time: use rotate: week there.

steps/<step>/items.json in the run then has a rotation section per language (the window, how many pages have been checked so far and how many never) and each page its last_checked: the previous time Kaloko checked it, or null.

Keep a big run small

A shared run holds 300 MB as stored. HTML and JSON travel gzip-compressed, so the page snapshots count for about a tenth of their size on disk; the screenshots are what adds up. Stack pages are captured whole, so a typical long page stores a screenshot of about 600 KB and a thumbnail of about 180 KB (the thumbnail is as tall as the page). That fills a run at roughly 400 pages.

An SEO family needs the page, not a picture of it. capture: { screenshot: thumb, full_page: false } keeps only a 640 px thumbnail of the first screen, about 25 KB, which is enough to recognise the page in the stack:

    items: { robots: true, match: '^/([a-z]{2}/)?eshop/', limit: 100, rotate: week }
    capture: { screenshot: thumb, full_page: false }

capture: { full_page: false } alone keeps a sharp first screen (about 70 KB), and capture: { screenshot: thumb } alone a thumbnail of the whole page. Leave the defaults on families where someone reviews the whole page or a semantic check reads what is below the fold.

When a run comes close to the limit, kaloko share names the largest steps, so you know which family to trim, and says so when a stack captured whole takes most of the room.

6. Walk it every week on GitHub Actions

npx kaloko schedule export github --scenario qa/flows/seo-squared-west.yml --env production --every week --at 5

The command writes a workflow that walks the scenario on Monday at 5:00 UTC, evaluates it and shares the run. It needs the secret KALOKO_TOKEN (Tester role, upload scope). Export one workflow per scenario file, at different hours, and raise timeout-minutes in the workflow for the big ones. When your config says that every scenario names its own project (a comment, or a product with projects:), give the scenario project: seo or another of them; kaloko validate warns when it is missing, and a share without it can end with HTTP 404.

Without GitHub Actions, kaloko schedule add walks the same scenario on Kaloko's side (Business plan). It reads stacks from sitemaps and robots.txt, takes a base_url per language and decides the checks that need only the page's elements, without screenshots; each stack page counts against the monthly budget of hosted pages. Structured data, answer-engine and locale checks stay "not evaluated" there, so for the full SEO and AEO packs the CLI on GitHub Actions is still the right place. More in Check pages on a schedule.

7. Read the results into a dashboard

Every shared run has its health: findings by severity, pack and step, and what is new or fixed since the previous week. For a dashboard:

  • GET /api/v1/orgs/<org>/scenarios/<id>/latest/health/aggregate?by=locale,step,check counts the newest run per language, content family and check, with the most affected pages and how many results are new or fixed since last week. …/latest/health/diff lists them page by page, each with the week it first failed. A token with the read:health scope reads these and nothing else, which suits a dashboard that pulls once a week. The shapes are in Health API for dashboards; MCP has get_health_aggregate and get_health_diff.
  • The health.changed webhook tells you after each run when something is new or fixed.
  • GET /api/v1/orgs/<org>/health?project=<project> or MCP get_health { project } gives the trend of the project; get_health { scenario } the newest run of one scenario.
  • MCP get_stack_items { run_id, step, status?, criterion?, query? } lists the pages of one step with their fields (jsonld_types, og_title), status and failing checks, for example every e-shop page that fails HC112.
  • In the run folder, steps/<step>/items.json holds the same per page, and its structured_data counts pages per schema.org type, pages without structured data and pages with invalid JSON-LD. kaloko health --json prints the findings of the local run.

A weekly chart of "pages without structured data" and "new health errors" per content family is usually enough. When a number jumps, open the run on the canvas and filter the stack by the failing check.

8. Hand the fixes to whoever fixes them

A finding is half the work; the editor still has to find the page in the CMS. Give every page its way back:

  • an item script returns edit_url (the page in the CMS) and content_ref (the record a content API knows it by) next to path;
  • or the stack gets a resolver that looks them up for the pages walked this week:
    items: { robots: true, match: '^/([a-z]{2}/)?eshop/', limit: 100, rotate: week, resolve: steps/resolve.mjs }
// steps/resolve.mjs
export default async (item, { locale }) => {
  const res = await fetch(`https://cms.example.com/api/pages?path=${encodeURIComponent(item.path)}&locale=${locale}`)
  const page = res.ok ? await res.json() : null
  return page ? { edit_url: `https://cms.example.com/pages/${page.id}/edit`, content_ref: `page:${page.id}` } : {}
}

A page the resolver fails on, or does not answer for within 15 seconds, is walked anyway, without the link, and the walk says how many. The page detail on the canvas then shows Edit in CMS, and the stack's CSV carries both columns. For the whole list:

npx kaloko export findings --format csv --out fixes.csv
npx kaloko export findings --format json --locale de --step eshop

Each row is one failing check on one page in one language: the URL, the check, its evidence, edit_url, content_ref and the command that walks that page again (kaloko walk --steps eshop --items <page> --locales de). The JSON goes straight to an agent with a content API, for Squared the MCP tools that propose, apply and verify a change. After the fix, that one command checks the page again without walking the rest, also when a rotating stack has moved on to other pages; such a walk does not count as a week of the rotation.

Work through findings, not pages

Two hundred product pages without structured data in Polish are one problem in the product template, not two hundred. Health → Findings of the scenario (the link next to each scenario on the health page) groups what is open by check, site, language and step: one row per problem, with its severity, how many pages it hits, a few of them with their edit link, and the week it first appeared. Acknowledge a finding when someone is on it, or ignore it with a reason ("old blog, moving to the new CMS in November"); the decision stays with it from week to week, and a finding is fixed once none of its pages fails. A dashboard or an agent reads the same through GET …/scenarios/<id>/findings or MCP list_findings.

If the team works in Jira, Linear, GitHub Issues or Plane, a Developer / Tester can let the scenario open one issue per new finding at or above a severity (PUT …/scenarios/<id>/findings/sync { "tracker": "jira", "min_severity": "error" }). Kaloko then comments when the number of pages changes a lot and closes the issue when the finding is fixed. Routes split the work: technical checks (canonical, hreflang, structured data) to the developers' GitHub repository, content checks (descriptions, thin pages, low click-through) to the marketers' Plane project. With traffic data (section 9) each issue says how many clicks and impressions the pages get. The details are in Health API for dashboards.

9. Fix the pages people actually see first

Two hundred missing descriptions are a long list. Search Console knows which of those pages people see in search, and Kaloko can use that. Export the Pages table from Search Console (Performance, Pages, Export, CSV), put it next to the scenario, and name it:

traffic:
  file: traffic/search-console-pages.csv

The export goes stale, so once the weekly run works, let it ask Search Console itself. Create a service account in Google Cloud, add its e-mail to the property as a user, put the path of its JSON key in GOOGLE_APPLICATION_CREDENTIALS (a repository secret in GitHub Actions), and replace the file with the property:

traffic:
  gsc: { property: sc-domain:example.com }

Every run then asks for the clicks, impressions, CTR and position of every page over the last 28 days, once per run. ga4: { property: "123456789" } adds sessions and key events by landing page the same way.

What changes:

  • kaloko export findings puts the findings on the most seen pages first and adds clicks, impressions, ctr, position, sessions and impact to each row, so the content team starts at the top of the CSV;
  • the page index on the canvas has Impressions and Clicks columns; click one to sort by it;
  • the seo pack adds HC127 to each stack: pages seen often in search but clicked less than half as often as the site's pages at similar positions. The title and description in the results are the usual suspects.

The formula and every key are in Configuration file. Data from other SEO tools (ranked keywords, AI visibility) is not joined yet.

On this pageOn this page