# Tool Reference

Every tool the Kafkai MCP server exposes, grouped by what it does.
Tool names are stable identifiers — your agent sees exactly these
names.

To see the tools in use before reading them one by one, start with the
[Example Prompts](https://kafkai.com/en/prompts/) page; each prompt there lists the tools
the agent calls behind it.

## If you already use an SEO tool

The same jobs have other names there. This table maps them to the
tools that answer them.

| What an SEO tool calls it | Kafkai tool |
|---|---|
| Content gap analysis | `kafkai_get_catchup_keywords` |
| Keyword research, keyword suggestions | `kafkai_get_complement_keywords` |
| Topic clustering | `kafkai_get_keyword_clusters` |
| Competitor discovery | `kafkai_find_competitors` |
| Backlink profile | `kafkai_get_backlinks` |
| Link intersect, backlink gap | `kafkai_get_link_gaps` |
| Rank tracking (when you ask, not daily) | `kafkai_get_ranking_changes` |
| SERP check | `kafkai_check_search_results` |
| Marketplace rank check (Amazon, Google Shopping) | `kafkai_check_marketplace_results` |

## Conventions

- **Responses are JSON.** Every tool returns a JSON document.
  Successful responses include a `next_step_suggestion` field: advice
  the server computes for the agent's next move (which tool to call,
  or what to search the web for). Agents follow these hints without
  special prompting.
- **Prices.** Every tool's description states its price, so the agent
  can tell a free call from a paid one before it calls. A free tool says
  so. The rates are in [Credits and Billing](https://kafkai.com/en/docs/credits/).
- **Usage reporting.** Metered tools append a `_usage` object showing
  what the call cost and your remaining balance. See
  [Credits and Billing](https://kafkai.com/en/docs/credits/).
- **Limits.** `limit` arguments are capped server-side (100 for
  keyword lists, 50 for clusters). Asking for more returns the cap,
  not an error. Lists longer than the cap are read a page at a time —
  see [Reading a long list](#reading-a-long-list) below.
- **Identifiers.** Projects are addressed by `project_id` (from
  `kafkai_list_projects`), competitors by `competitor_domain` (from
  `kafkai_list_competitors`), and publishing destinations by
  `destination_id` (from `kafkai_list_publishing_destinations`).

## Reading a long list

A research run can return far more keywords than one call should
carry, so the list tools return one page at a time. Every paged
response says where its page sits:

- `count` — rows in this response.
- `total_matching` — rows in the whole list the page came from.
- `offset` — rows skipped to reach this page.

To read the next page, call the same tool again with `offset` raised
by your `limit`. While rows remain, `next_step_suggestion` names the
exact offset to use, so an agent walks a long list without being told
how. A `count` smaller than your `limit` means the page is the last
one. An offset past the end returns no rows and reports how many
there are, rather than failing.

The keyword, cluster, backlink, Search Console, Bing Webmaster and
analytics list tools all take `offset`. The tools that return one short
list — projects, competitors, publishing destinations — do not.

Each page is a separate call carrying its own flat call fee, so one
call of 100 rows costs less than five calls of 20. Read in the
largest pages a tool allows, and stop once you have what you need.
See [Credits and Billing](https://kafkai.com/en/docs/credits/).

## Projects and competitors

### kafkai_list_projects

Lists your projects with id, site URL, status, location, and
keyword and competitor counts. This is the usual first
call — later tools need the `project_id` it returns. Each project also
carries its `setup_reminders` (see [Setup reminders](#setup-reminders)).
Free.

Arguments: none.

### kafkai_get_project_summary

A full overview of one project: site metadata, niche, location,
keyword counts per 4C strategy and for your own ranking baseline,
the competitor list, and the blocks that say what data exists —
`authority` (your site's strength next to each competitor's),
`backlinks` (whether backlink data exists for your site and each
competitor, with the whole-profile totals, and a `next_step_suggestion`
naming which backlink tool to call), `search_console` (whether
Kafkai can read your site's Google Search Console property, whether
the domain is verified for your account (`domain_verified`) and the
window its data covers, with a `next_step_suggestion` that names the
two Search Console tools or the step still missing: verifying the
domain, or granting access) and `bing_webmaster` (the same for your
site in Bing Webmaster Tools, with the week its data covers) and
`marketplaces` (for each marketplace the project has used: the
identity on file, the number of keywords checked and the time of the
newest check; an empty list until you set an identity or run
`kafkai_check_marketplace_results`). The
response also names a `recommended_strategy` — the strategy with the
most keyword opportunities — with the reason. `last_research` is the
project's latest research run — a full update, or the research an added
competitor bought: `pending` while it is still running, then its verdict
(`success`, `partial` or `failed`) with the reason when something failed.
`setup_reminders` lists the setup steps that are not done yet (see
[Setup reminders](#setup-reminders)). Free.

`site_metadata` is a short summary of your homepage as Kafkai last read
it. It is not the whole page. It holds:

- `url` and `code` — the address Kafkai read and the response code.
- `page_title` and `description` — the page's title and meta
  description.
- `headings` — the text of the first H1 to H3 headings, at most 20.
- `excerpt` — the first 1,000 characters of the page text.
- `fetched_at` — when Kafkai read the page, in UTC.

Kafkai reads the homepage when the project is created and again at the
start of every `kafkai_update_keywords` run.
When the latest read fails, Kafkai keeps the page from the read before
and adds `fetch_error` and `fetch_error_at`, so the summary may be
out of date. While no page is stored at all, the research an added
competitor starts tries the read again too. A project created before
Kafkai recorded the time has no `fetched_at` until its next update.

Arguments:

- `project_id` — the project to summarise.

### kafkai_list_competitors

Lists the competitor sites tracked in a project, with each
competitor's keyword count and research `status`. A competitor whose
research failed reads `failed`, with the reason in `error`; its keyword
lists are incomplete, and the response's `next_step_suggestion` says how
to retry — `kafkai_update_keywords` researches every domain again, or
remove the competitor and add it again for the competitor fee. The
response highlights the `top_competitor` by keyword count and carries
`last_research`, the project's latest research run. Free.

Arguments:

- `project_id`

### kafkai_find_competitors

Finds the sites a project's site competes with in search, from the
keywords the site actually ranks for — not from a guess about its
homepage. Kafkai takes the domains that rank for the same keywords in
the project's country (the 1,000 largest sites on the web excluded),
scores each by how much of the two keyword footprints overlap, sizes
it against your site with the same winnability rule the 4C tools use,
and reads what each site is. Unrelated domains are dropped.
Competitors the project already tracks are flagged `already_tracked`,
so the list reads as "who else".

The response holds two lists:

- `competitors` — the sites that compete with yours.
- `comparison_sites` — review sites, comparison sites, directories
  and listicle publishers. They are not competitors, so Kafkai keeps
  them out of `competitors` and returns them separately. If your
  business grows through affiliate and comparison sites, these are
  the sites to watch.

Each row in both lists carries `domain`, `relationship` (`direct`,
`adjacent`, or `unknown` when it could not be judged; always
`aggregator` in `comparison_sites`), `winnability`, `rank` (0–1000),
`intersections` (the keywords you share), `overlap` (that count as a
share of both footprints, 0–1), `avg_position`, `etv`,
`keywords_count`, `sample_keywords` and `already_tracked`.
`filtered_out` counts the domains Kafkai dropped, by reason:
`unrelated` for sites that are not in your market, and `unreachable`
for sites whose domain or hostname no longer resolves. Keyword data keeps
listing a site for a while after it closes, so Kafkai resolves each
candidate's domain name over DNS and drops the ones that cannot be
resolved. `site`
gives your own keyword count, traffic estimate and rank. Competitors
are ordered direct competitors first, then winnable before avoid, then
by overlap. Comparison sites are ordered by overlap.

Three things to know when reading the rows:

- A site Google does not rank for anything yet is answered from the
  searches its customers make (`method` is `customer_searches`, and
  `seed_keywords` lists them): who ranks on page one for those,
  smallest sites first. `overlap`, `etv` and `keywords_count` are
  empty on that path and `winnability` is `unknown`.
- Kafkai returns the candidates and the evidence; which of them
  matter is your agent's reading. Adding one is a separate, priced
  step: `kafkai_add_competitor`.
- To follow a comparison site, add it with `kafkai_add_competitor`.
  Kafkai then tracks its keywords and positions like any competitor.
  To see which comparison sites are on page one for a keyword, call
  `kafkai_check_search_results`.

Carries its own call fee, higher than a plain read, because the tool
buys fresh competitor, authority and judgement data rather than
returning what the project already holds; the per-row amount is the
same as every other read and counts the rows in `competitors` only.
Rows in `comparison_sites` are not charged. The answer is cached for
a day, so a repeat call returns the same lists. See
[Credits and Billing](https://kafkai.com/en/docs/credits/).

Arguments:

- `project_id`
- `limit` — max competitors to return (default 10, max 20). The same
  limit caps `comparison_sites`.

### kafkai_get_competitor_analysis

A focused analysis of one competitor: its brand description, the
keywords it ranks for that you do not (Catch-up), and the keywords
you both rank for (Compete). Higher base cost than a plain list.

Every keyword carries `competitor_previous_rank` and
`competitor_rank_change` (and `our_previous_rank` and
`our_rank_change` on Compete rows): the move since Kafkai's previous
measurement.

Arguments:

- `project_id`
- `competitor_domain` — from `kafkai_list_competitors`.
- `include_history` — set to true to include each keyword's dated
  positions: `competitor_history` for this competitor, `our_history`
  where you rank too.

## Keyword research — the 4C strategies

The four strategy tools share their shape: each returns keyword
objects with search volume, keyword difficulty, CPC, ranks, the
ranking page's SERP title and description where relevant, tags, and
freshness timestamps (`first_seen`, `last_updated`). A `recommended`
subset highlights the strongest starting keywords by volume and
difficulty.

Every rank is dated. Each keyword also carries the move of each side
since Kafkai's previous measurement: `our_previous_rank` and
`our_rank_change` where you rank, `competitor_previous_rank` and
`competitor_rank_change` where the competitor does. A positive change
means the position moved up. Catch-up, Consolidate and Compete also
accept `include_history`: set it and each keyword carries the dated
positions Kafkai has recorded for every side that ranks
(`our_history`, `competitor_history`), oldest first, with unchanged
positions collapsed. For "what moved over the last three months", use
`kafkai_get_ranking_changes` below instead.

Catch-up, Consolidate and Compete each measure your site against a
competitor, so they stay empty until the project has at least one.
Complement does not — it works from your own topics, with or without
competitors. To see what your site ranks for when no competitor is
registered, use `kafkai_get_ranked_keywords` below.

All four take the same arguments:

- `project_id`
- `limit` — max keywords to return (default 20, max 100).
- `offset` — rows to skip, for paging (default 0). The response's
  `next_step_suggestion` names the next offset while more rows remain,
  and `total_matching` says how many rows there are in all.
- `include_history` — Catch-up, Consolidate and Compete only. Set to
  true to include the dated positions of each side that ranks.

### kafkai_get_catchup_keywords

Catch-up: keywords competitors rank for that you do not — your
content gaps. Each keyword shows which competitor ranks and with what
title, so the agent knows exactly what page it is up against.

### kafkai_get_consolidate_keywords

Consolidate: keywords you already rank for that competitors do not —
the territory that is working and worth strengthening.

### kafkai_get_compete_keywords

Compete: keywords where both you and a competitor rank — head-to-head
battles. Both ranks are returned, so the agent can pick fights where
the gap is small.

### kafkai_get_complement_keywords

Complement: related keywords that neither you nor your competitors
target yet — what to add next to the topic map. Each keyword is
returned once, however many of your topics suggested it, so `limit`
counts distinct keywords.

### kafkai_get_keyword_clusters

Semantic clusters: groups of related keywords that one comprehensive
article can cover together. Each cluster carries its average search
volume, difficulty, and CPC, plus its member keywords. The response
recommends the highest-volume cluster.

Arguments:

- `project_id`
- `limit` — max clusters (default 10, max 50).
- `offset` — clusters to skip, for paging (default 0). The response's
  `next_step_suggestion` names the next offset while more clusters
  remain, and `total_matching` says how many there are in all.

## Your own rankings

### kafkai_get_ranked_keywords

Every keyword your site already ranks for, and how each position has
moved. This is not one of the 4C strategies: those compare your site
against a competitor, while this one reads your own positions
directly. It works on a project with no competitors at all, which
makes it the first useful call on a brand-new project.

Each keyword returns your current position, the previous one, the
change since the last measurement, whether the keyword is newly
ranking, plus search volume, difficulty, CPC and the page that ranks.
A `progress` object tallies what improved, declined, stayed flat and
is new, and how many keywords sit in the top 3 and top 10.

Set `include_history` and each keyword also carries the positions
Kafkai has recorded over time, oldest first — enough to chart a trend.
Unchanged positions are collapsed, so you get the moves rather than
one point per update.

Three things to know when reading the numbers:

- A keyword here may also appear under Consolidate or Compete. This is
  your whole ranking picture, not a slice of it.
- `progress` counts only the keywords this call returned, not the
  whole project. The project-wide figure is `total_ranked_keywords`.
- On the first call for a new project there is no earlier Kafkai
  measurement to compare against, so the change is counted from the
  position first seen.

Positions refresh when you run `kafkai_update_keywords` — that is what
adds the next point to each keyword's history.

Arguments:

- `project_id`
- `limit` — max keywords to return (default 20, max 100).
- `offset` — rows to skip, for paging (default 0). The response's
  `next_step_suggestion` names the next offset while more rows remain,
  and `total_matching` says how many rows there are in all.
- `include_history` — set to true to include past positions for each
  keyword.

## Ranking changes over time

### kafkai_get_ranking_changes

Which keywords gained or lost positions over a period — for your own
site, one competitor, or every competitor at once. Every rank Kafkai
measures is dated, so the tool compares each keyword's position at the
start of the period with its position now and sorts the biggest moves
first. It answers "what moved in the last three months", "where is
this competitor slipping", "which keywords did I lose", and "what are
my opportunities from competitors' falling rankings".

Each keyword returns its `movement` — `improved`, `declined`, `new`
(ranks now, did not at the period start) or `lost` (ranked at the
period start, does not now) — with `current_rank` and `measured_at`,
`baseline_rank` and `baseline_measured_at`, `rank_change` (positive
when the position moved up), `first_seen`, search volume, difficulty,
CPC, the ranking page and `source`. `source` is `measured` for a
position Kafkai measured, or `search_console` for a row Kafkai filed
from your Search Console queries when nothing was measured for it: a
28-day average position on the site URL, with impressions as the
volume and difficulty 0. The two are never compared with each other,
and a Search Console row that Kafkai later replaces with a measured one
is dropped, not reported as lost. Competitor reports add
`competitor_domain`, `our_rank` and `our_rank_source`. `our_rank` is
where your site sits on the same keyword right now. Kafkai uses a
measured rank when it has one. When nothing was measured, it uses your
Search Console average position, and `our_rank_source` is
`search_console`. A competitor sliding on a keyword you sit close
behind, or do not rank for yet, is the opening to write for.

A `summary` counts what improved, declined, stayed unchanged, is new
and is lost across every keyword measured for the site, not just the
rows returned. Unchanged keywords are counted there and left out of
the list.

Three things to know when reading the numbers:

- Updates run on demand, so there is no measurement for "exactly 90
  days ago". The baseline is the latest measurement at or before the
  period start, and `baseline_measured_at` says when that was.
- When tracking began inside the period (`period.tracked_since`), the
  first measurement stands in for the period start, and the keywords
  from that first run are not "new".
- Rows are merged per keyword, so a keyword that moved between
  strategies keeps one continuous history.

Positions refresh when you run `kafkai_update_keywords` — that is what
adds the next dated measurement.

Arguments:

- `project_id`
- `competitor_domain` — empty for your own site, a competitor's domain
  (from `kafkai_list_competitors`) for that competitor, or `all` for
  every competitor merged into one list (the response then also
  carries `competitor_domains` and a `by_competitor` breakdown).
- `days` — length of the period in days (default 90, max 365).
- `movement` — `all` (default; every kind of move but unchanged),
  `improved`, `declined`, `new` or `lost`.
- `limit` — max keywords to return (default 20, max 100).
- `offset` — rows to skip, for paging (default 0). `total_matching`
  counts the rows that match `movement`; `summary` still counts the
  whole site.

## Backlinks

Who links to your site and to each competitor, how strong those sites
are, when each link was last seen, and how many links each site gained
and lost over time. Kafkai returns the data; the reading — what the
linking sites have in common, which lost link is worth chasing — is
your agent's.

Kafkai fetches backlinks as part of every research run: for the site
and each competitor when a project is created, for the new competitor
when one is added, and for every site on `kafkai_update_keywords`. The
three read tools below answer from that snapshot; `kafkai_update_backlinks`
refreshes backlinks alone, without re-buying keyword data. Every
response says when the snapshot was taken (`as_of`), and a site that
has not been fetched yet says so instead of returning empty rows.

### kafkai_get_backlinks

The sites linking to your site or to one competitor — one row per
referring domain, its strongest link, strongest first. It answers "who
links to competitor X", "how strong are the sites linking to me", and,
with `status` set to `lost`, "which links did competitor X lose that I
could win": every lost row names a site that once linked to a page like
`target_page` and stopped, with `last_seen` dating the loss.

Each row carries `referring_domain`, `referring_page`, `target_page`,
`page_title`, `anchor`, `link_type`, `dofollow`, `link_rank`,
`referring_page_rank` and `referring_domain_rank` (0–1000, higher is
stronger), `spam_score`, `platform_types`, `country`, `first_seen`,
`last_seen`, `is_lost`, `is_new`, `is_broken` and `links_from_domain`.

Two things to know when reading the numbers:

- `profile` holds the whole link profile: `domain_rank`,
  `backlinks_total`, `referring_domains_total`, the nofollow and broken
  counts, and the link type, platform, country and TLD mixes. Quote
  those totals for the size of the profile.
- The rows are a sample of it. Kafkai stores the strongest link from up
  to 1,000 referring domains, and the strongest links lost within the
  last year. `coverage` says how many rows are stored and whether the
  live sample is complete, so an agent can say "the strongest 1,000 of
  18,452" rather than imply it saw everything.

Arguments:

- `project_id`
- `competitor_domain` — empty for your own site, or a competitor's
  domain (from `kafkai_list_competitors`). One site per call.
- `status` — `live` (default), `lost` (links that disappeared within
  the last year) or `all`.
- `limit` — max rows to return (default 20, max 100).
- `offset` — rows to skip, for paging (default 0). The response's
  `next_step_suggestion` names the next offset while more rows remain.

### kafkai_get_backlink_changes

How many backlinks and referring domains a site gained and lost over a
period — your own site, one competitor, or every site in the project
side by side. Kafkai keeps a daily new/lost count for each site (a year
of history from the first fetch), so the period is summed from that,
with a month-by-month breakdown. It answers "how many links did
competitor X win in the last three months", "is their link building
accelerating", and "am I keeping pace".

Each site row carries `status` and `as_of`, `totals_now` (`backlinks`,
`referring_domains`, `domain_rank`), `totals_previous` (the same totals
as of the fetch before, with its own `as_of`), `totals_check`,
`period_totals` (`new_backlinks`, `lost_backlinks`, `net_backlinks`,
`new_referring_domains`, `lost_referring_domains`,
`net_referring_domains`), `by_month`, and `data_from` / `data_to` — the
days the stored history actually covers. A site whose `status` is not
`ready` has no counts yet.

A total is the size of the link index for the site on the date it was
fetched, and that index gets rebuilt: a spam network dropped, a
recount. So the difference between two totals is not links gained or
lost — the daily counts are. A rebuild can move one total and leave
the other alone, so `totals_check` checks each one. For
`referring_domains` and for `backlinks` it gives the change from
`totals_previous` to `totals_now`, the daily counts for the days
between the two fetches, and the gap between them (`change`,
`net_from_daily_counts`, `unexplained`, `consistent`). The top-level
`consistent` is `false` when either total disagrees, and `note` says
which. A total's `consistent` is `null` when Kafkai cannot compare it:
the total is missing, or the fetch before is older than the daily
counts Kafkai keeps. The top-level `consistent` is `null` when neither
total can be compared. Quote totals with their dates, and read gains
and losses from `period_totals`.

Arguments:

- `project_id`
- `competitor_domain` — empty for your own site, a competitor's domain
  (from `kafkai_list_competitors`), or `all` for your site and every
  competitor, one row each.
- `days` — length of the period in days (default 90, max 365).

### kafkai_get_link_gaps

The sites that link to two or more of your competitors but not to you
— the link gap. One row per referring domain, strongest first, with the
link it gives each competitor (`referring_page`, `target_page`,
`anchor`, `dofollow`, `link_rank`, `last_seen`). A site that already
links to several competitors covers your topic and accepts links to
sites like yours, so it is the first place to ask for one. Kafkai
returns the rows; which sites to approach, and what to offer them, is
your agent's reading.

Each row carries `referring_domain`, `competitor_count`,
`referring_domain_rank` (0–1000, higher is stronger), `spam_score`,
`country` and `links`. `competitors_with_data` and
`competitors_without_data` say which competitors the answer covers.

Two things to know when reading the rows:

- It needs backlink data for your own site — that is how "not linking
  to you" is decided — and for at least `min_competitors` competitors.
  Until then the response names the sites still missing and how to
  fetch them.
- "Not linking to you" is judged against the stored sample of your live
  links (`own_site_coverage`, the same shape as `coverage` above), so a
  site outside that sample can appear in the list although it links to
  you.

Arguments:

- `project_id`
- `min_competitors` — how many competitors a site must link to before
  it counts as a gap (default 2, minimum 1). Pass `1` to see every site
  that links to any competitor but not to you.
- `limit` — max rows to return (default 20, max 100).
- `offset` — rows to skip, for paging (default 0). The response's
  `next_step_suggestion` names the next offset while more rows remain.

### kafkai_update_backlinks

Fetches fresh backlink data for your site and every competitor in a
project: the linking sites and their strength, the links lost in the
last year with the date each was last seen, and a year of daily
gained/lost counts. This is what the three read tools above answer from.

Backlinks are already fetched by `kafkai_create_project`,
`kafkai_add_competitor` and `kafkai_update_keywords`. Use this tool to
refresh them without re-buying keyword data — for a project created
before backlinks existed, after a failed fetch, or when a day-old
snapshot is not fresh enough.

The fetch runs in the background and takes about a minute per site. A
site fetched within the last day is skipped, and a site whose fetch is
still running is not fetched twice, so calling this twice in a row costs
nothing extra. The response lists the sites it is fetching now
(`domains`), the ones it skipped (`skipped_fresh`) and the ones already
running (`in_flight`).

Charges a backlinks-only fee once per site actually fetched — smaller
than a full update, because no keyword data is bought; see
[Credits and Billing](https://kafkai.com/en/docs/credits/).

Arguments:

- `project_id`

## Domain verification

Kafkai serves a site's own private data — Search Console, Bing
Webmaster Tools, analytics and Google Analytics today, other sources as
they are added — only to an account that has proved it controls the
domain. The proof is one code, unique to your account and that domain,
published in one of two ways:

- **A DNS TXT record** on the project's registered (apex) domain. A
  project on `blog.example.com` is proved at `example.com`, and
  `example.co.jp` is proved at `example.co.jp` (the Public Suffix List
  decides what "registered" means, so a two-label country suffix is kept
  whole). One record opens every subdomain project for your account.
- **An HTML meta tag** in the page's `<head>`, for a site whose DNS you
  cannot edit — one on a hosted platform, say. The tag must be on the
  page at the domain itself, never on a subdomain of it: on a shared
  host every tenant can edit their own subdomain and none of them owns
  the domain. A platform subdomain is a registered domain in its own
  right, so `alice.blogspot.com` proves itself with its own tag.

Two accounts can both verify one domain — a site owner and their agency,
say — each with their own code. Both tools are free.

1. Call `kafkai_verify_domain` with the `project_id`. The response gives
   both proofs, and either one works: `dns_record` (`type`, `name` and
   `value` — `kafkai-verification=` followed by the code) and `meta_tag`
   (the exact `<meta>` tag to paste).
2. Publish the one you can — the record at the DNS provider for the
   domain, or the tag in the `<head>` of the page at the domain.
3. Call `kafkai_check_domain_verification`. Kafkai looks for the record
   first, and for the tag on the page at the domain when the record is
   not there. When either one is present, `status` becomes `verified`.
   DNS changes usually show within minutes but can take up to 48 hours,
   so call again later if nothing was found yet.

Kafkai re-checks verified domains periodically. A record or tag that is
later removed stops the data until it is put back; the code stays the
same, so there is nothing to redo but the record or the tag.

The same record, tag, check button and status are on the
[Domains page](https://kafkai.com/en/accounts/domains/) of your account, one entry per
domain — use it when you would rather copy them from a browser than
through the agent. Both paths share one code per domain.

### kafkai_verify_domain

Starts verifying the project's domain, or returns the existing code,
with both ways to publish it: the DNS record and the HTML meta tag.
Calling it again never changes the code.

Arguments:

- `project_id`

The response carries `domain` (the project's registered domain, where
the record goes), `status` (`pending` or `verified`), `dns_record`
(`type`, `name`, `value`), `meta_tag` (the `<meta>` tag to paste),
`verified_at`, `last_checked`, `last_error` and a `next_step_suggestion`.

### kafkai_check_domain_verification

Looks for the record, then for the meta tag, and reports the result in
the same shape as `kafkai_verify_domain`. Nothing found keeps `status`
at `pending` and says in `last_error` what was looked for. A lookup that
got no answer (a timeout) changes nothing; try again in a few minutes.
Calling this before `kafkai_verify_domain` is fine: the code is created
and both proofs are in the answer.

Arguments:

- `project_id`

## Search Console

Your own Google Search Console data, read by two tools and refreshed
by a third, free one. Kafkai's
ranking data is a sample of search results; Search Console is what
Google actually recorded for your site — every query it appeared for,
with real clicks, impressions, click-through rate and average
position. Together they answer what the rankings alone cannot: what
people searched, which pages they clicked, and what changed.

Both tools describe one period: the latest 28-day window Kafkai has
stored, compared with the 28 days before it. Every row and the
property-wide `totals` carry `clicks_change`, `impressions_change` and
`position_change` against that prior window. `position_change` is
positive when your site moved up the page — the same sign the ranking
tools use.

Two steps stand between a project and its data. While
`search_console.status` is `not_connected`, both tools name the first
one still missing in their `next_step_suggestion`, so your agent can
pass it on to you.

1. Verify the domain (see Domain verification above). Until then Kafkai
   serves nothing for the domain, not even whether a property exists.
2. Grant Kafkai read access to the property. This is one step in Search
   Console, and shares nothing but an email address: open the property
   in [Google Search Console](https://search.google.com/search-console),
   go to **Settings** > **Users and permissions** > **Add user**, enter
   the Kafkai reader address and choose the **Restricted** permission
   level. The address is in the `next_step_suggestion` once the domain
   is verified. For a walkthrough with screenshots, see
   [Connect Google Search Console](https://kafkai.com/en/docs/google-search-console/).

Kafkai picks the property up at the next research run
(`kafkai_update_keywords`) or the next call of
`kafkai_update_search_console`, whichever comes first, and backfills
16 months of history. Until the first sync finishes the status is
`syncing`. After that, every research run refreshes the data, and
`kafkai_update_search_console` refreshes it alone, for free.

Two things to know when reading the numbers, both Google's doing:

- Google leaves out the queries it anonymises, so the query rows add
  up to less than the property's true totals. `totals` are exact, and
  `coverage` reports the impressions the query rows carry
  (`visible_impressions`), the exact total (`total_impressions`) and
  the share between them (`visible_impressions_share`). The share is
  measured over the rows the call returns, so it describes what you can
  actually see.
- Google Discover reports pages and totals but no queries, so
  `search_type='discover'` works with the pages and trend views only.

### kafkai_get_search_console_data

The queries your site appears for, the pages that earn the traffic, or
the daily totals — three views of one period.

- `view='queries'` (default): one row per search query in the current
  window — `query`, `clicks`, `impressions`, `ctr`, `position`, the
  prior window's numbers under `prior`, and the three change fields.
- `view='pages'`: one row per page of your site, summed from Google's
  daily page figures, which are exact.
- `view='trend'`: one row per day, oldest first, taken from the recent
  end of the prior and current windows — enough to see the day traffic
  turned. Pass `limit=100` for the whole series.

Every response carries `search_console` (`property`, `status`,
`domain_verified`),
`window`, `prior_window` and `totals` (`current`, `prior` and the
change fields). Use it next to `kafkai_get_ranked_keywords`: a query
here that the ranking data does not show is a real search Kafkai's
sample missed.

Arguments:

- `project_id`
- `view` — `queries` (default), `pages` or `trend`.
- `order_by` — for the queries view: `impressions` (default), `clicks`
  or `position` (best first). Pages are always ordered by impressions.
- `contains` — only queries (or page URLs) containing this text,
  case-insensitive. The trend view has neither, so it ignores this and
  does not echo it back.
- `search_type` — `web` (default) or `discover`.
- `limit` — max rows to return (default 20, max 100). For the trend
  view it is a number of days counted back from the most recent, so
  `limit=100` returns the whole series in one call. `total_matching`
  always says how many days the two windows hold.
- `offset` — rows to skip, for paging (default 0). The trend view
  counts back from the most recent day, so `offset` steps further into
  the past. The response's `next_step_suggestion` names the next offset
  while more rows remain.

### kafkai_get_search_console_insights

What to work on first, computed by Kafkai from your Search Console
data. Five kinds of flag, each a query or page with the numbers behind
it in `evidence` and a `score` to rank by within its kind:

- `striking_distance` — queries ranking just off page one (positions
  8–20 by default) with real impressions. Score: the extra clicks
  expected from reaching position 5.
- `ctr_gap` — queries whose click-through rate is far below what their
  position normally earns on your site: usually a title or snippet
  problem, not a ranking problem. Score: clicks lost.
- `cannibalisation` — one query split across two or more of your
  pages, each taking a real share of the impressions. Score: the
  impressions at stake.
- `new_query` — queries your site newly appears for, compared with the
  prior window. Score: impressions.
- `decay` — pages whose clicks dropped hard against the prior window,
  computed for web search and Google Discover separately. Score:
  clicks lost.

The response's `definitions` states each rule with the thresholds in
force, and `counts` says how many flags of each kind exist. Scores
compare within a kind only — the units differ. Kafkai computes the
flags; deciding what to change is your agent's reading of the
evidence, with `kafkai_get_search_console_data` for the surrounding
rows.

Arguments:

- `project_id`
- `insight_type` — `all` (default) or one of `striking_distance`,
  `ctr_gap`, `cannibalisation`, `new_query`, `decay`. With `all`,
  `limit` and `offset` apply per kind.
- `limit` — max rows to return per kind (default 20, max 100).
- `offset` — rows to skip per kind, for paging (default 0).

### kafkai_update_search_console

Fetches the latest Search Console data for your site, without a
research run. Free.

Every research run already fetches Search Console data at its end.
Use this tool when you want fresh Search Console figures without
buying keyword and backlink data again — for example, when the stored
window is a few days old. It also picks up a property you have just
granted Kafkai access to, so you do not need a research run to
connect it.

The fetch runs in the background. A refresh takes about a minute. The
first fetch of a property loads 16 months of history and takes
several minutes.

Google publishes Search Console data once a day, about two days
behind. So Kafkai fetches each property at most once a day. A second
call within 24 hours fetches nothing, and the response says when the
next fetch is available. A research run counts as that day's fetch.

The two steps above come first: verify the domain, then grant Kafkai
read access. While a step is missing, the response's
`next_step_suggestion` names it.

The response carries:

- `queued` — `true` when a fetch started, `false` when nothing was
  fetched.
- `search_console` — `property`, `status` and `domain_verified`, the
  same block the read tools return.
- `next_sync_available` — when the next fetch can start.
- `next_step_suggestion` — what to call next: usually
  `kafkai_get_search_console_data` once the fetch has finished.

Arguments:

- `project_id`

## Bing Webmaster Tools

Your own Bing Webmaster Tools data, read by two tools and refreshed by
a third, free one — the Bing counterpart of the Search Console tools.
Bing is the second search engine in Japan with its own data tool, and
its totals include the impressions your site gets in Copilot chat,
which nothing else shows.

The data is coarser than Google's, and the tools say so rather than
hide it:

- Bing reports its top queries and pages per **week**. Both read tools
  describe one period: the latest week Kafkai has stored against the
  week before it. Every response carries `granularity: "week"`, and
  Kafkai never adds weekly rows up into a longer total.
- Bing keeps only its top queries and pages, with a threshold it does
  not publish, so the rows add up to less than the site's totals by an
  unknown share. `coverage` is therefore `null`, with `coverage_note`
  saying why. `totals` are exact: Kafkai sums them from Bing's daily
  figures, which cover every Bing surface, Copilot chat included, and
  carry no position.
- Every query and page row has two positions: `position`, the average
  position of the impressions (the one the insights use), and
  `click_position`, the average position of the clicks.

Two steps stand between a project and its data, the same two as for
Search Console. While `bing_webmaster.status` is `not_connected`, the
tools name the first one still missing in `next_step_suggestion`.

1. Verify the domain (see Domain verification above). One verification
   covers every data source, so a domain verified for Search Console is
   done. Until then Kafkai serves nothing for the domain, not even
   whether a Bing site exists.
2. Grant Kafkai read access to the site. Open the site in
   [Bing Webmaster Tools](https://www.bing.com/webmasters), choose
   **User management** in the left menu, then **Add user**. Enter the
   Kafkai Bing reader address and choose the **Read only** role. The Bing
   reader is a different account from the Google one, so the address
   differs; it is in the `next_step_suggestion` once the domain is
   verified. For the steps in full, see
   [Connect Bing Webmaster Tools](https://kafkai.com/en/docs/bing-webmaster-tools/).

Kafkai picks the site up at the next research run
(`kafkai_update_keywords`) or the next call of
`kafkai_update_bing_webmaster`, whichever comes first. A fetch takes
under a minute: Bing has no history to backfill, every fetch returns
everything Bing keeps. Until the first fetch finishes the status is
`syncing`.

### kafkai_get_bing_webmaster_data

The queries your site appears for in Bing, the pages that earn the
traffic, or the daily totals — three views of one week.

- `view='queries'` (default): one row per search query among Bing's
  top queries for the current week — `query`, `clicks`, `impressions`,
  `ctr`, `position`, `click_position`, the prior week's numbers under
  `prior`, and the three change fields.
- `view='pages'`: one row per page among Bing's top pages for the
  current week, same fields with `page` in place of `query`.
- `view='trend'`: one row per day, oldest first, taken from the recent
  end of the prior and current weeks. Daily rows carry no position.
  Pass `limit=100` for the whole series.

Every response carries `bing_webmaster` (`property`, `status`,
`domain_verified`), `granularity`, `window`, `prior_window`, `totals`
(`current`, `prior` and the change fields), `coverage` (always `null`)
and `coverage_note`. Use it next to `kafkai_get_search_console_data`:
a query strong in one engine and absent in the other is a real
difference between the two.

Arguments:

- `project_id`
- `view` — `queries` (default), `pages` or `trend`.
- `order_by` — for the queries view: `impressions` (default), `clicks`
  or `position` (best impression position first). Pages are always
  ordered by impressions.
- `contains` — only queries (or page URLs) containing this text,
  case-insensitive. The trend view ignores this and does not echo it
  back.
- `limit` — max rows to return (default 20, max 100). For the trend
  view it is a number of days counted back from the most recent.
- `offset` — rows to skip, for paging (default 0). The trend view
  counts back from the most recent day.

### kafkai_get_bing_webmaster_insights

What to work on first in Bing, computed by Kafkai from one week of
Bing's top rows against the week before. Four kinds of flag, each a
query or page with the numbers behind it in `evidence` — both Bing
positions included — and a `score` to rank by within its kind:

- `striking_distance` — queries whose average impression position is
  just off page one (8–20 by default) with real impressions. Score: the
  extra clicks expected from reaching position 5.
- `ctr_gap` — queries whose click-through rate is far below what their
  position normally earns on your site in Bing. Score: clicks lost.
- `new_query` — queries among this week's top queries that were not
  among last week's. Score: impressions.
- `decay` — pages whose clicks dropped hard against the week before.
  Score: clicks lost.

Cannibalisation is not computed for Bing: Bing does not report which of
your pages share a query. The response's `definitions` states each rule
with the thresholds in force, and `counts` says how many flags of each
kind exist. These are one week of data — confirm a flag against
`kafkai_get_search_console_insights` before acting on it alone.

Arguments:

- `project_id`
- `insight_type` — `all` (default) or one of `striking_distance`,
  `ctr_gap`, `new_query`, `decay`. With `all`, `limit` and `offset`
  apply per kind.
- `limit` — max rows to return per kind (default 20, max 100).
- `offset` — rows to skip per kind, for paging (default 0).

### kafkai_update_bing_webmaster

Fetches the latest Bing Webmaster Tools data for your site, without a
research run. Free.

Every research run already fetches Bing data at its end. Use this tool
when you want fresh Bing figures without buying keyword and backlink
data again. It also picks up a site you have just granted Kafkai
access to, so you do not need a research run to connect it.

The fetch runs in the background and takes under a minute. Bing updates
its totals daily and its top queries weekly, so Kafkai fetches each
site at most once a day. A second call within 24 hours fetches nothing,
and the response says when the next fetch is available. A research run
counts as that day's fetch.

The two steps above come first: verify the domain, then grant Kafkai
read access. While a step is missing, the response's
`next_step_suggestion` names it.

The response carries:

- `queued` — `true` when a fetch started, `false` when nothing was
  fetched.
- `bing_webmaster` — `property`, `status` and `domain_verified`, the
  same block the read tools return.
- `next_sync_available` — when the next fetch can start.
- `next_step_suggestion` — what to call next: usually
  `kafkai_get_bing_webmaster_data` once the fetch has finished.

Arguments:

- `project_id`

## Tracking setup

What a site tracks, read from the public file its tag manager loads.
Every site on Google Tag Manager loads one public file per container,
and the file holds the tags the site runs. Kafkai reads it for your own
site and every competitor. Your agent can then explain how a competitor
markets and sells, and report when that setup changes.

The data answers four questions:

- **Which paid channels a competitor buys.** A Meta pixel means Facebook
  and Instagram ads. A Yahoo! JAPAN tag means Yahoo ads. A LinkedIn tag
  means business buyers.
- **What a competitor counts as a win.** Event names such as
  `cv_onlinedemo` or `order_completed` show the offers it tests.
- **How a competitor sells.** Marketing automation means a sales team
  follows up on leads, chat tools mean live sales, and attribution tools
  mean real ad spend.
- **What changed.** A new pixel means a new channel, and a new event
  means a new campaign.

This data does not show ad spend, traffic per channel or what a lead is
worth. Literal conversion values are rare: Kafkai found them in one of
six sites tested.

Tag names are not in the file, so Kafkai reports what each tag does, not
what the site's team called it. Vendor names are reported exactly as
found on the site.

Kafkai reads the sites at the end of every research run: all of them
when a project is created or updated, and only the new competitor when
one is added. To read them at any other time, call
`kafkai_update_tracking_stack`. Both ways are free. Kafkai reads only
when you ask, and it does not check sites on a schedule.

### What each status means

| `status` | Meaning |
|---|---|
| `ready` | Kafkai read at least one container or Google tag. |
| `no_tag_manager` | Kafkai read the homepage and found no tag manager or Google tag. `vendors` lists any tool the page loads directly. |
| `unreadable` | Kafkai could not read the homepage or any of its containers. |
| `not_fetched` | Kafkai has not read this site yet. |

Neither `no_tag_manager` nor `unreadable` means the site has no tracking.
Kafkai cannot see these setups:

- tags served from the site's own server (server-side tagging),
- tags that a consent manager adds to the page by script,
- sites that block automated readers.

A response with `unread_containers` is a partial reading: Kafkai read
some of the site's containers but not all of them.

### kafkai_get_tracking_stack

Returns the tracking setup of the project's site and competitors. Free.

Each entry in `domains` carries:

- `domain`, `is_own_site`, `status` and `fetched_at`, the time of the
  reading.
- `containers` and `unread_containers` — the container IDs found on the
  page.
- `ga4_ids` — Google Analytics 4 measurement IDs.
- `ads_account_ids` — Google Ads account IDs.
- `ads_conversion_actions` — how many Google Ads conversion actions the
  site runs.
- `literal_conversion_values` — conversion values written directly in
  the tags, each with its `currency` (`null` when the tag names none).
- `conversion_event_names` — the event names as the site's team typed
  them.
- `vendors` — tools found, grouped as `ads`, `analytics`,
  `marketing_automation`, `attribution`, `ab_testing`, `chat` and
  `other`. A group with no tools is left out.
- `changes_since_previous` — added and removed `vendors`,
  `conversion_event_names` and `ads_account_ids`, with the date of the
  reading compared in `compared_with`. It is `null` on the first reading
  and whenever either reading is partial, so a failed read never appears
  as a removal.
- `last_readable` — on an `unreadable` site, the newest earlier reading.

Arguments:

- `project_id`
- `domain` — only this site, either the project's site or one of its
  competitors. Leave it out for every site in the project.

### kafkai_update_tracking_stack

Reads the project's site and every competitor again, in the background.
Free. A site read within the last 24 hours is reused, so calling this
tool often does not fetch the same files again. An unreadable site can
be retried after one hour.

The response carries:

- `queued` — domains being read now.
- `reused` — domains read recently enough to keep.
- `in_flight` — domains another call is already reading.
- `next_step_suggestion` — what to call next. Reading takes about a
  minute.

Arguments:

- `project_id`

The `tracking_stack` block of `kafkai_get_project_summary` and
`kafkai_get_competitor_analysis` gives the counts for each site and
`changes_since_previous`. The vendor and event lists are in
`kafkai_get_tracking_stack`.

## Analytics

Your own traffic analytics, read by one tool. Search Console covers
the search angle — what people searched for and what Google recorded.
Analytics covers the whole visit: how many people came, which pages they
opened, where they came from, and what they used to browse. It answers
what the search data cannot: how much traffic the site gets overall,
and what visitors do once they arrive.

Two steps stand between a project and its data, and the `analytics.status`
block (`not_verified`, `not_configured`, `unavailable`, `ready`) names
the one still missing in `next_step_suggestion`:

1. Verify the domain (see Domain verification above). Until then
   Kafkai serves nothing for the domain, not even whether analytics
   tracking exists for it.
2. Ask Kafkai support to set up tracking for the site. Kafkai sets it
   up on its own analytics instance; there is no customer-side setup,
   and nothing to connect afterwards: the first call finds the site
   automatically and keeps it. A site set up a moment ago can take up
   to ten minutes to appear. A project on a subdomain uses the site of
   its registered domain when it has none of its own.

`unavailable` means Kafkai could not reach its analytics service on
this call; it says nothing about whether tracking exists. Try again in
a minute.

Unlike Search Console there is nothing to wait for: the data is read
live at call time, so once the status is `ready` the next call returns
what the site holds right now.

### kafkai_get_analytics_data

Traffic, pages, referrers, visitor location and devices, in 21
reports. By default it covers the last 30 days; pass
`period='day'` and `date='last30'` for a daily time series.

Every response carries `analytics` (`status`, `domain_verified`,
`id_site`, `site_url`), the `report`, a short `description` of the
report, the `period` and `date` in force, `count` and `rows`. While
more rows remain, `next_step_suggestion` names the `offset` for the
next page.

Arguments:

- `project_id`
- `report` — one of: `summary` (default), `pages`, `entry_pages`,
  `exit_pages`, `page_titles`, `outlinks`, `downloads`, `referrers`,
  `search_engines`, `keywords`, `social`, `websites`, `campaigns`,
  `campaign_sources`, `campaign_contents`, `countries`, `regions`,
  `cities`, `device_types`, `browsers`, `browser_versions`,
  `operating_systems`, `screen_resolutions`.
  `summary` returns one metrics row — visits, unique visitors,
  actions, bounce rate and average visit duration; the rest return
  a list of rows. For an ad or a tagged link, `campaigns` lists the
  campaign names (`utm_campaign`), `campaign_sources` the source and
  medium (`utm_source` / `utm_medium`), and `campaign_contents` the
  content tag (`utm_content`) that tells ad variants apart.
- `period` — `day`, `week`, `month`, `year` or `range`. Empty
  defaults to `range`.
- `date` — empty defaults to the last 30 days. Examples: `today`,
  `last30`, `2024-01-01,2024-01-31` (for `period='range'`).
- `segment` — optional segment definition to filter visits.
- `limit` — max rows to return for list reports (default 20, max
  100). Ignored by `summary`.
- `offset` — rows to skip, for paging (default 0).

### kafkai_get_ga_analytics_data

The customer's own Google Analytics 4 data: traffic, pages, landing
pages, channels, source/medium, countries, cities, devices, browsers,
operating systems and key events. Read live from the customer's GA4
property — not stored, so there is nothing to sync or wait for once
access is granted.

Same domain-verification gate as Search Console and analytics. The
`ga_analytics.status` block (`not_verified`, `not_connected`,
`ambiguous`, `unavailable`, `ready`) names the step still missing in
`next_step_suggestion`:

1. Verify the domain (see Domain verification above).
2. In Google Analytics, go to Admin › Property access management ›
   Add users, enter the Kafkai reader address and pick the Viewer role.
   Kafkai finds the property on the next tool call — no research run
   needed.

`ambiguous` means more than one GA4 property claims the site; contact
Kafkai support with the property id to use.

Every response carries `ga_analytics` (`status`, `domain_verified`,
`property_id`, `property_name`, `stream_uri`), the `report`, a short
`description`, `start_date` and `end_date` in force, `count`, `total`,
`subject_to_thresholding` and `rows`. GA4 can take 24-48 hours to
process data, and may hide small rows for privacy —
`subject_to_thresholding` says when that happened. Numbers will not
match Search Console: GA4 counts sessions from all sources, Search
Console counts clicks from Google Search.

Arguments:

- `project_id`
- `report` — one of: `summary` (default), `daily`, `pages`,
  `landing_pages`, `channels`, `source_medium`,
  `organic_landing_pages`, `countries`, `cities`, `devices`,
  `browsers`, `operating_systems`, `key_events`. `summary` returns
  one metrics row; the rest return a list of rows.
- `start_date` — ISO date (`2026-08-01`) or GA4 relative date
  (`30daysAgo`, `yesterday`, `today`). Empty defaults to 30daysAgo.
- `end_date` — ISO date or GA4 relative date. Empty defaults to
  yesterday.
- `limit` — max rows to return (default 20, max 100). Ignored by
  `summary`.
- `offset` — rows to skip, for paging (default 0).

## SERP intelligence

### kafkai_get_keyword_serp_data

Everything known about one keyword in a project: who ranks (domains,
SERP titles, descriptions, URL types), your rank, competitor ranks,
rank changes, search volume, difficulty, CPC, and tags. The response
includes a `ranking_context` interpretation — for example, "competitor
ranks #3, you don't rank — write content to capture this demand".
If the exact keyword is not found, near matches are returned instead.
Higher base cost.

Arguments:

- `project_id`
- `keyword` — the exact keyword to look up (falls back to a
  contains-match).

### kafkai_check_search_results

Checks which sites are on page one of Google for keywords you choose,
in the project's country and language, and reports what changed since
the last check. Use it to monitor the sites that rank for your main
keywords: whether your site is on page one, which comparison and
review sites rank, and who entered or left since last week.

This tool differs from `kafkai_get_keyword_serp_data` in two ways.
It returns every site on page one, not only your site and your
competitors. And the keyword does not have to be in the project's
research data — you can check any keyword.

For each keyword, `checks` holds one entry:

- `keyword` — the keyword as checked (trimmed and lowercased).
- `checked_at` — when Kafkai fetched the page.
- `fetched_fresh` — `true` when this call fetched the page, `false`
  when Kafkai returned a page stored within the last 24 hours.
- `own_site_position` — your site's best position on the page, or
  `null` when Kafkai did not find it on page one. When `note` is set,
  `null` does not mean the site is absent.
- `unread_addresses` — the number of results whose address Kafkai
  could not read. `0` for a page that was read in full.
- `note` — what the unread addresses leave unknown, or `null`.
- `results` — the organic results of page one, up to 10 rows.
- `changes` — what changed since the previous stored page. `null` on
  the first check of a keyword, and when the previous page has no
  readable address.

Each row in `results` carries `position` (among organic results),
`rank_absolute` (among every element on the page, the number the
keyword tools report), `domain`, `url`, `title`, `description` and
three flags:

- `is_own_site` — the result belongs to the project's site.
- `is_tracked_competitor` — the result belongs to a competitor the
  project tracks.
- `links_to_own_site` — the site has a live link to your site in
  Kafkai's backlink data. That data is a sample, and
  `own_site_backlink_coverage` says how complete it is. So `false`
  means "no link in the sample", and `null` means Kafkai has no
  backlink data for your site yet. A link that goes through an
  affiliate network's redirect domain is not detected.

**When Kafkai could not read an address.** Sometimes Kafkai could not
read the address of a result. That row still has its correct `title`
and `description`, but:

- `domain` is `null`.
- `is_own_site`, `is_tracked_competitor` and `links_to_own_site` are
  `null`. This means "unknown", not `false`.
- `url` is Google's link to the page, not the page's own address.

A row can also have a `domain` while its `url` is still Google's
link: Kafkai read the site from the result's breadcrumb.

If your site is not among the rows Kafkai could read and at least one
address is unread, `own_site_position` is `null` and `note` says that
the site may still be on page one. Your agent reads the titles of the
rows with a `null` domain before it reports the site as absent.
If an unread row sits above your site, `note` says that the site
may rank higher than `own_site_position`.

`changes` holds `previous_checked_at` and three lists, compared site
by site: `entered` (sites new on page one), `left` (sites no longer
on page one) and `moved` (sites whose position changed; `change` is
positive when the site moved up). An unread address makes lists
unknown, and Kafkai returns `null` for them instead of a guess:
`entered` is `null` when the previous page had an unread address,
`left` is `null` when the latest page has one, and `moved` is `null`
when either page has one.

Four things to know:

- **Kafkai checks only when you call the tool.** Nothing runs on a
  schedule. To follow the changes, call the tool again with the same
  keywords, for example once a week.
- **A page stored within the last 24 hours is returned again.** Kafkai
  does not fetch it a second time, and that keyword adds nothing to
  the cost.
- **Kafkai returns who ranks, not what the pages say.** To see whether
  a comparison page lists your service, and at which place, your agent
  opens the `url` of the row and reads the page.
- **A keyword whose fetch failed is listed in `failed` and is not
  charged.** This includes a page where Kafkai could not read any
  address. Call the tool again to retry it.

Cost: 1 credit per call, plus 5 credits for each keyword Kafkai
fetches fresh. A call with 10 keywords costs at most 51 credits. A
call that returns only stored pages costs 1 credit. A call that is
refused, or that returns no page at all, costs nothing. The response
reports the charge in `billing`. See
[Credits and Billing](https://kafkai.com/en/docs/credits/).

Arguments:

- `project_id`
- `keywords` — the keywords to check, as a list. Up to 10 per call; a
  longer list is refused.

## Marketplaces

A project is a website. A marketplace such as Amazon is one more
channel the same business sells on. These two tools answer "how does
my product do on Amazon" and "who is in the Google Shopping results
for my keyword". Setup does not change: you keep one project per
domain, and nothing here runs until you call a tool.

Kafkai supports two marketplaces:

| `marketplace` | What Kafkai fetches |
|---|---|
| `amazon` | Amazon search results |
| `google_shopping` | Google Shopping results |

You bring the keywords. Kafkai has no list of the keywords a listing
ranks for.

### kafkai_check_marketplace_results

Checks who ranks on a marketplace for keywords you choose, in the
project's country, and reports whether your own listing moved since
the last check. Use it for an online shop: where your product is on
Amazon for a keyword, who is above it and at what price, and which
sellers are in the Google Shopping results.

For each keyword, `checks` holds one entry:

- `keyword` — the keyword as checked (trimmed and lowercased).
- `fetched_at` — when Kafkai fetched the page.
- `served_from_store` — `false` when this call fetched the page,
  `true` when Kafkai returned a stored page.
- `result_count` — the number of listings on the whole stored page.
- `own_listing_position` — the best `rank_absolute` of your organic
  listings, or `null` when none is on the page or no identity is on
  file.
- `own_listings` — every row of the page that is your own listing,
  including rows below `limit`.
- `results` — the first `limit` listings of the page.
- `change_since_previous` — your position now and on the previous
  stored page. `null` on the first check of a keyword.

Each row in `results` carries:

- `rank_absolute` — the position among every listing on the page,
  sponsored listings included.
- `rank_group` — the position within the row's own type.
- `type` — `organic` or `sponsored`.
- `listing_id` — the ASIN on Amazon. On Google Shopping it is Google's
  product id, and it is empty for a row that has none.
- `title`, `url`, `price`, `currency`, `rating`, `rating_count`.
- Amazon only: `is_amazon_choice`, `is_best_seller` and
  `bought_past_month`.
- Google Shopping only: `seller`, the shop name as Google shows it.
- `is_own_listing` — on Amazon, `true` or `false` once the project's
  ASINs are on file (see `kafkai_set_marketplace_identity`), matched
  exactly. `null` when no ASIN is on file. Always `null` on Google
  Shopping: read the `seller` names there.

`change_since_previous` holds `previous_fetched_at`,
`own_listing_position`, `previous_own_listing_position` and `change`.
`change` is positive when your listing moved up. It is `null` when
your listing is missing from either page.

The two marketplaces answer in different ways:

- **Amazon answers inside the call.** The call takes about 20 seconds.
- **Google Shopping answers in two calls.** The first call queues the
  fetch and lists the keywords under `pending`. Call the tool again
  with the same keywords about a minute later to read the pages.
  Kafkai charges for Google Shopping on that second call, when the
  pages arrive. A call while every keyword is still pending costs
  nothing.

Seven things to know:

- **Kafkai checks only when you call the tool.** Nothing runs on a
  schedule, on project creation or on a research run.
- **A page stored within the last 24 hours is returned again.** Kafkai
  does not fetch it a second time, and that keyword adds nothing to
  the cost.
- **Kafkai returns who ranks.** Reading the rows — who is cheaper, who
  has more reviews — is your agent's work.
- **A page with no listing is an answer.** The marketplace shows
  nothing for that keyword. Kafkai returns the check with a
  `result_count` of 0 and charges it like any page.
- **A keyword whose fetch failed is never charged.** On Amazon it is
  listed in `failed`; call the tool again to retry it.
- **A Google Shopping keyword is charged when its page arrives.**
  Queueing it is free, but your balance must cover the pages the call
  would return. Kafkai charges each page the first time a call returns
  it. If a fetch fails, the next call with that keyword fetches it
  again and lists it under `retried`. Kafkai does this up to 2 times.
  After that the keyword is listed in `failed`, and Kafkai does not
  fetch it for 24 hours.
- **A project holds a limited number of unread Google Shopping
  pages.** A page is unread while it is queued, or ready and not
  returned yet. A call that would go over the limit is refused and
  charges nothing. The refusal states the limit and lists the unread
  keywords under `unread`. Read them first; reading pages in a call
  makes room for new keywords in the same call.

Cost: 1 credit per call, plus 5 credits for each new page the call
returns. A call with 10 keywords costs at most 51 credits. A call
that returns only pages you have already paid for costs 1 credit. A
call that is refused, or that returns no page, costs nothing — so
queueing Google Shopping keywords and checking on them while they are
`pending` is free. The response reports
the charge in `billing`. See [Credits and Billing](https://kafkai.com/en/docs/credits/).

Arguments:

- `project_id`
- `marketplace` — `amazon` or `google_shopping`.
- `keywords` — the keywords to check, as a list. Up to 10 per call; a
  longer list is refused.
- `limit` — rows returned per keyword, from the top of the page
  (default 20, max 100). Kafkai stores the whole page either way.

Supported countries. The check works when the project's country is
on the list for that marketplace:

| `marketplace` | Supported project countries |
|---|---|
| `amazon` | Australia, Brazil, Canada, France, Germany, India, Japan, Singapore, the United Arab Emirates, the United Kingdom and the United States |
| `google_shopping` | Australia, Brazil, Canada, Denmark, France, Germany, India, Indonesia, Japan, Malaysia, Portugal, Singapore, South Korea, Thailand, the United Arab Emirates, the United Kingdom and the United States |

For a project in another country, the tool refuses the call and
charges nothing.

### kafkai_set_marketplace_identity

Tells Kafkai which listings on a marketplace are the project's own.
A marketplace does not know your domain, so Kafkai matches rows
against the ids you register. Free.

- For `amazon`, pass `asins`: the ASINs of your products. An ASIN is
  the 10 letters and digits after `/dp/` in a product page URL.
  `kafkai_check_marketplace_results` then sets `is_own_listing` on
  every Amazon row, on stored pages too.
- For `google_shopping`, pass `seller_name`: the shop name as Google
  Shopping shows it. Kafkai stores the name and does not match rows
  on it yet.

The value you pass replaces what is on file. Pass the full list every
time, and an empty list to clear it. Call the tool with neither
`asins` nor `seller_name` to read what is on file.

This tool needs no domain verification. Result pages are public, and
the list only decides which rows Kafkai flags. Without it the check
still works: every row then has `is_own_listing: null`.

Arguments:

- `project_id`
- `marketplace` — `amazon` or `google_shopping`.
- `asins` — Amazon only. The full list of the project's ASINs, up to
  200.
- `seller_name` — Google Shopping only. The shop's display name.

## Project management

These tools change data. Research runs asynchronously — queue it,
keep working, and check back with `kafkai_get_project_summary`.

### kafkai_create_project

Creates a project for a site, adds any competitors you give, and
queues the full keyword research — including the backlinks of the site
and of each competitor (see [Backlinks](#backlinks)). Priced per site
researched: a base fee for your site plus a competitor fee for each
competitor you give; see [Credits and Billing](https://kafkai.com/en/docs/credits/).

Arguments:

- `site_url` — the site to analyse, for example
  `https://example.com`. Required.
- `site_name` — a display name; defaults to the URL.
- `description` — a short description of the site.
- `location_code` — the country whose search results the project
  targets. Required, with no default. The code is 2 followed by the
  country's ISO 3166-1 numeric code: Japan is `2392`, Malaysia `2458`,
  the United States `2840`. Call the tool without it and it fails for
  free, listing every market you can pick.
- `competitors_url` — a list of competitor site URLs. Optional.

Competitors are optional, and you can add them later with
`kafkai_add_competitor`. Without them, Catch-up, Consolidate and
Compete stay empty — each needs a competitor to compare against — but
Kafkai still collects your own ranking baseline and Complement
keywords, so a project starts useful with nothing but a domain and a
country.

Before Kafkai creates the project, it checks that every
competitor's domain or hostname resolves. If even one domain cannot be
resolved, the call is refused: no project is created and nothing is
charged. The response lists the failing addresses in
`unreachable_competitors`. Correct them or leave them out, then call
the tool again.

A project is locked to one country. Research for the wrong country
costs the same and tells you nothing, which is why Kafkai asks instead
of guessing.

The response carries `setup_steps`: an ordered list of the steps that
let Kafkai read the site's own data. Each step has a `step` name, a
`title`, `instructions` that name the tool or page to use, and
`requires` — the step that must be done first, or `null`:

1. `verify_domain` — call `kafkai_verify_domain`, publish the DNS TXT
   record or the meta tag it returns, then call
   `kafkai_check_domain_verification`. You can also do this on the
   Domains page of your account. See
   [Domain verification](#domain-verification).
2. `connect_search_console` — add the Kafkai reader address to your
   Search Console property with Restricted permission.
3. `connect_google_analytics` — add the Kafkai reader address to your
   Google Analytics property as Viewer.
4. `connect_analytics` — ask Kafkai support to set up Kafkai's
   analytics tracking for your site. Kafkai finds the site by itself
   once tracking exists.
5. `connect_bing_webmaster` — add the Kafkai Bing reader address to
   your site in Bing Webmaster Tools as Read only.

The steps are free and optional. Skip them if you do not own the site,
or skip one service you do not use. Steps 2–5 need step 1 first. A
step that is already done is left out — a domain your account already
verified for another project, say — and `setup_steps_note` explains the
list. When the project already exists, the response carries the same
list.

### kafkai_add_competitor

Adds one competitor to an existing project and fetches only that
competitor's data — its keywords and its backlinks. Existing
competitors and the site itself are not re-fetched, so this is much
cheaper than a full update: it charges the competitor fee once.

The research runs in the background and is logged like a full update;
the response carries its `update_log_id`. Check `kafkai_list_competitors`
a few minutes later: the competitor's `status` reads `ready` when its
data is in, or `failed` with the reason in `error`. While the research
runs, `kafkai_update_keywords` and the delete tools are refused for the
project.

Kafkai first checks that the competitor's domain or hostname
resolves. If it cannot be resolved, the call is refused with "Kafkai could not
reach this site. Check the address and try again." and nothing is
charged. A site whose domain or hostname resolves is accepted even if it
returns a parking page or an error.

Arguments:

- `project_id`
- `competitor_url`

### kafkai_delete_competitor

Removes one competitor from a project, together with every keyword
Kafkai collected for it and that keyword's ranking history. Use it
when a competitor was added by mistake and its unrelated keywords are
polluting the Catch-up, Consolidate and Compete lists. Free.

The deletion is permanent, so the tool runs in two steps:

1. Call it without `confirmation_token`. Nothing is deleted. The
   response lists what would be removed (keywords per strategy,
   research sessions, ranking history) and what would be kept, and
   includes a `confirmation_token` valid for 15 minutes.
2. Your agent shows you that summary and asks you to confirm. Only
   then does it call the tool again with the same `project_id` and
   `competitor_domain` plus the token. The competitor is marked for
   deletion and its data is removed in the background; check with
   `kafkai_list_competitors` a few minutes later.

A token is bound to one competitor and one account. Reused for a
different competitor, or after it expires, it is refused and nothing
happens. The deletion is refused while a keyword update for the
project is running; wait for it to finish and ask again.

Arguments:

- `project_id`
- `competitor_domain` — from `kafkai_list_competitors`; a full URL is
  accepted too.
- `confirmation_token` — empty for the preview; the token from the
  preview to run the deletion.

### kafkai_update_keywords

Queues a fresh ranking update for the whole project: all strategies
and your own ranking baseline are re-fetched, ranks on existing
keywords refresh, and keywords that dropped out are marked lost. This
is what adds the next point to each keyword's position history, so run
it before asking `kafkai_get_ranked_keywords` or
`kafkai_get_ranking_changes` what moved. The backlinks of the site and
of every competitor are refreshed in the same run (a site fetched within
the last day is reused). Your homepage is read again at the start of
the run, so `site_metadata` in `kafkai_get_project_summary` shows the
page as it is now; a homepage Kafkai cannot read does not fail the run.
Priced like creation: the base fee for your site plus the competitor
fee for every competitor in the project.

Only one research run per project happens at a time; a second request
while one is running — including the research an added competitor
triggers — is refused. A project whose deletion you have confirmed
cannot be updated either; that request is refused before anything is
charged. Updates run on demand — Kafkai does not re-fetch rankings on
its own schedule.

Arguments:

- `project_id`

### kafkai_delete_project

Deletes a project and everything in it: competitors, every keyword with
its ranking history, and research sessions. Use it for a project you no longer need, or
one that was set up with the wrong site. Free.

The deletion is permanent, so the tool runs in two steps:

1. Call it without `confirmation_token`. Nothing is deleted. The
   response lists what would be removed (competitors, keywords per
   strategy, research sessions) and what is not touched, and
   includes a `confirmation_token` valid for 15 minutes.
2. Your agent shows you that summary and asks you to confirm. Only
   then does it call the tool again with the same `project_id` plus
   the token. The project is marked as deleting and its data is removed
   in the background; check with `kafkai_list_projects` a few minutes
   later.

A token is bound to one project and one account. Reused for a
different project, or after it expires, it is refused and nothing
happens. Posts already published to your own site stay live, and
publishing destinations and publication records belong to your account
and are kept. The deletion is refused while a keyword update for the
project is running; wait for it to finish and ask again.

Arguments:

- `project_id`
- `confirmation_token` — empty for the preview; the token from the
  preview to run the deletion.

### Setup reminders

A customer who skips the setup steps at creation still hears about them.
`kafkai_get_project_summary` and `kafkai_list_projects` carry
`setup_reminders`: the setup steps that are not done yet, in this order —
verify the domain, then Search Console, Google Analytics, analytics and
Bing Webmaster Tools. Each entry has a `step` name, a `title`,
`instructions` (the same text as the `setup_steps` of
`kafkai_create_project`) and `mute`, the exact call that stops it.
`setup_reminders_note` tells your agent to mention them once per
session, not on every call.

- While the domain is not verified, the only reminder is
  `verify_domain`. The other steps need it first.
- A step that is done is not listed. A source you connect after you
  muted it is not listed either.
- A muted source is not listed. When you mute every source, the
  verification reminder stops too.
- A source that Kafkai could not reach on this call is not listed. Its
  summary block says to try again.
- `kafkai_get_project_summary` has the final answer. `kafkai_list_projects`
  reads stored data only, so it can still show a Google Analytics or
  analytics step that the summary finds done: the summary looks for a
  new property or site, the list does not. Your agent calls the summary
  for a project before it offers that project's reminders.

### kafkai_update_project_settings

Changes a project's settings. The one setting today is
`setup_reminders`: which setup reminders Kafkai shows for the project.
Ask your agent to stop a reminder when you do not own the site, or do
not use one of the services — "stop reminding me about Google
Analytics for example.com". Free.

Muting hides the reminder only. It disconnects nothing and changes no
data. To connect a muted source later, follow its setup step as
before. The Connections section of the project page in your account
shows "Reminders off" next to a muted source that is not connected.
The page has no switch: you change the setting through your agent.

Arguments:

- `project_id`
- `setup_reminders` — the sources to change, each set to `true`
  (remind) or `false` (mute), for example
  `{"google_analytics": false}`. Sources: `search_console`,
  `google_analytics`, `analytics`, `bing_webmaster`. Sources you leave
  out keep their setting. Leave the argument out to read the current
  settings.

The response has `settings.setup_reminders` (each source and whether
its reminder is on) and the `setup_reminders` still shown. An unknown
source name is refused with the list of valid ones, and nothing
changes.

## Publishing

Kafkai does not write articles. Your agent writes the piece from the
data above, then hands the finished text to Kafkai to publish. Kafkai
keeps a snapshot of exactly what it sent — title, body, language — as
the publication record; it holds no other copy of the article.

To set up a WordPress site as a destination, see
[Connect WordPress](https://kafkai.com/en/docs/wordpress/). You need a WordPress username
with write permission and an Application Password — not the WordPress
login password.

### kafkai_list_publishing_destinations

Lists the active publishing destinations on your account — WordPress
sites and webhooks — with each one's `destination_id`, name, type and
URL. Destinations belong to the account, not to a project. Free.

Arguments: none.

### kafkai_add_publishing_destination

Adds a destination. For WordPress, pass the site URL and an application
password; for a webhook, the endpoint URL and its credentials. The
credentials are stored encrypted and never returned. Free.

Arguments:

- `name` — a label for the destination (unique on your account).
- `destination_type` — `wordpress` (default) or `webhook`.
- `url` — the site or endpoint URL.
- `auth_type` — `basic` (default). Basic Auth is the only method the
  publishers send, so it is the only one offered.
- `credentials` — the login details for that auth type. For WordPress:
  `username` and `password`, where the password is an Application
  Password, not the WordPress login password. A WordPress destination
  without both is rejected. For a webhook: `username`
  (or `email`) and `password`, sent as HTTP Basic Auth. A webhook
  without them is called with no authentication.

### kafkai_delete_publishing_destination

Removes a destination. Posts already published through it stay where
they are, and their publication records are kept. Free.

Arguments:

- `destination_id`

### kafkai_publish_article

Publishes text your agent wrote to one destination and returns where
the post went (`external_url`). Pass the body as HTML in `content`, or
as Markdown in `content_markdown` — when `content` is empty, the
Markdown is rendered to HTML for you, and webhook destinations also
receive the Markdown as written. The post goes up as a draft unless you
ask for it to go live, so you can review it on your own site first.
Free.

To update an existing post instead of creating a new one, pass its
`external_id` (returned by a previous publish call). This edits the
existing post on the destination rather than creating a duplicate.

To publish one article in several languages, call the tool once per
language, with `language` set (`en`, `ja`). Give every language version
the same `slug`: a receiver such as kafkai.ai uses the slug to link the
versions as translations. To update one version later, pass the
`external_id` that the call for that language returned.

Arguments:

- `project_id` — the project the article was written for; its market
  sets the default language.
- `destination_id` — from `kafkai_list_publishing_destinations`.
- `title`
- `content` — the body as HTML. Required unless `content_markdown` is
  given.
- `content_markdown` — the body as Markdown.
- `language` — e.g. `en` or `ja`. Defaults to the project's market
  language.
- `post_status` — `draft` (default) or `live`.
- `categories` — category names, e.g. `["Education", "Coffee"]`. On
  WordPress, categories that don't exist yet are created automatically.
  Webhook destinations receive the list as-is.
- `slug` — the URL slug for the post, e.g. `my-first-article`. Webhook
  destinations receive it as-is. Use the same slug for every language
  version of one article.
- `external_id` — the ID of an existing post on the destination to
  update instead of creating a new one. Use the `external_id` returned
  by a previous publish call for the same language. When omitted, a new
  post is created.
- `author` — the author's email or display name, as the destination
  knows it. Up to 255 characters.
- `excerpt` — a short summary for article listings. Up to 2,000
  characters.
- `seo_title` — the title shown in search results (the HTML `<title>`),
  when it differs from `title`. Up to 255 characters.
- `meta_description` — the text shown under the headline in search
  results. Up to 2,000 characters.
- `featured_image_url` — the public `http` or `https` URL of the
  featured image, up to 2,000 characters. The receiver downloads it.
  Kafkai rejects a URL whose host is private, local or internal
  (`localhost`, `10.0.0.5`, a name that resolves to such an address),
  so the receiver never downloads from its own network.

A value that breaks one of these rules is rejected before anything is
stored or sent.

`author`, `excerpt`, `seo_title`, `meta_description` and
`featured_image_url` are sent to webhook destinations only. WordPress
destinations ignore them for now. Kafkai stores all five on the
publication record with the title and body. Some webhook receivers
require `author` and `slug`; kafkai.ai requires both.

### Webhook request and response

This section is for the developer who builds a webhook receiver.

**Request.** Kafkai sends one `POST` to the destination URL for every
`kafkai_publish_article` call:

- Header `Content-Type: application/json`.
- HTTP Basic Auth (`Authorization: Basic …`) when the destination has a
  `username` (or `email`) and a `password`. Without them, no
  `Authorization` header is sent.
- No signature header.
- Kafkai waits 30 seconds for the response. It does not retry: a
  timeout or an error response fails the call.

The JSON body:

| Field | Sent | Value |
|---|---|---|
| `title` | always | The post title. |
| `content` | always | The body as HTML. Rendered from `content_markdown` when the agent gave only Markdown. |
| `status` | always | `draft` or `live`. |
| `content_markdown` | when not empty | The body as Markdown, as the agent wrote it. |
| `language` | when not empty | A language code such as `en` or `ja`. |
| `slug` | when not empty | The URL slug. Shared by every language version of one article. |
| `categories` | when not empty | A list of category names. |
| `author` | when not empty | The author's email or display name. |
| `excerpt` | when not empty | A short summary for listings. |
| `seo_title` | when not empty | The title for search results. |
| `meta_description` | when not empty | The text under the headline in search results. |
| `featured_image_url` | when not empty | A public `http`/`https` image URL to download. |
| `external_id` | on update only | The ID of the post to update. |

Example:

```json
{
  "title": "How to build an AI strategy",
  "content": "<p>Rendered HTML</p>",
  "content_markdown": "Markdown body",
  "status": "live",
  "language": "en",
  "slug": "build-ai-strategy",
  "author": "writer@example.com",
  "categories": ["AI Strategy"],
  "excerpt": "One or two sentences for listings.",
  "seo_title": "How to Build an AI Strategy | Example",
  "meta_description": "Text shown under the headline in search results.",
  "featured_image_url": "https://example.com/hero.jpg",
  "external_id": "123"
}
```

**Response.** Kafkai accepts status `200`, `201` or `202` with a JSON
body (`Content-Type: application/json`):

- `id` (or `external_id`) — required. The receiver's ID for the post.
  Kafkai returns it to the agent as `external_id`.
- `url` — the public or preview URL of the post. Kafkai returns it to
  the agent as `external_url`. When it is missing, Kafkai returns the
  webhook URL instead.

Any other status fails the call. Kafkai shows the agent the `error` or
`message` field of a JSON error body. A success status with an HTML
body, a non-JSON body or no ID also fails the call.

**Updates.** An update is the same `POST` to the same URL, with
`external_id` in the body. The receiver decides between create and
update from `external_id`: with it, change that post; without it,
create a new one.

**Languages.** One call sends one language version. An article in
English and Japanese is two requests with the same `slug` and a
different `language`. The receiver links the versions by the slug, and
returns a different `id` for each. Each version is later updated with
its own `id`.

## Account

### kafkai_get_account

Which Kafkai account this connection uses. Free.

If you connect more than one Kafkai account to your agents, ask the
agent "which Kafkai account am I connected to?". The agent calls this
tool and tells you. It also calls it before a tool that costs credits
when you say you have more than one connection, so you know which
account pays.

Returns:

- `email` — the email address you sign in to Kafkai with.
- `name` — the account name, empty when you have not set one.
- `connection` — how this agent is connected: `type` is `oauth` (you
  approved the agent in Kafkai) or `api_token` (you pasted a token from
  Kafkai), `label` is the agent's name or the token's name, and
  `authorized_at` is when you connected it.
- `credit_balance` — the account's balance.

Kafkai reads all of this from the connection itself. The tool takes no
arguments, so it cannot show any other account. If you connect a
shared agent, such as a team chat bot, everyone who uses that agent can
see this account's email address.

Arguments: none.

## Credits

### kafkai_get_credit_balance

Your current balance, lifetime totals, and the last ten transactions
with per-call cost breakdowns. Free — checking your balance never
costs credits.

Credits are valid for 90 days from the day they are added, and the
oldest are spent first. `expiring` lists every batch still unused with
its `valid_until` — the last day those credits can be spent — soonest
first, so an agent can tell you when to use what is left.

Every date and time is in UTC, and `time_zone` says so. `valid_until`
is a UTC day. `expires_at` is the exact moment the batch stops being
usable: 00:00 UTC on the day after `valid_until`. In Tokyo, that is
09:00 on that day. Ask your agent to convert `expires_at` to your own
time zone.

Arguments: none.

## Prompts

Besides tools, the Kafkai MCP server offers prompts: ready-made
routines your agent runs from start to end. A client that supports MCP
prompts lists them in its prompt or slash-command menu. Choosing one
gives the agent the routine's instructions. A prompt is free. The tools
the agent then calls cost what they always cost, and the routine tells
the agent to state the total before it starts.

| Prompt | What it does | Page |
|---|---|---|
| `kafkai_weekly_seo_plan` | The weekly check: ranking changes, page one, keywords to write next, links, Search Console fixes, then three actions. | [Playbook: Weekly SEO Plan](https://kafkai.com/en/docs/weekly-seo-plan/) |
| `kafkai_help` | Answers your questions about using Kafkai, from the current documentation, in your language. | [Kafkai Help for Your AI Agent](https://kafkai.com/en/docs/kafkai-help/) |

Arguments:

- `language` — `en` (default) or `ja`: the language of the
  instructions. The agent replies in your language either way.

Each prompt carries the same text as its page. If your client does not
list prompts, paste the line at the top of the page into your agent, or
install the page's skill file.
