ドキュメント » ツールリファレンス

ツールリファレンス

Kafkai MCPサーバーが提供する全ツールを、役割ごとに説明します。ツール名はそのまま識別子です。エージェントからも、この名前で参照します。

ツールを1つずつ読む前に全体の使い方を知るには、プロンプト例から始めてください。例ごとに、エージェントが裏で呼び出すツールを示しています。

共通仕様

  • 応答形式：すべてのツールがJSONを返します。成功した応答には next_step_suggestion が含まれます。次に呼び出すツールや、Webで検索すべき語を、サーバー側で判断した内容です。エージェントは特別なプロンプトなしで、この提案に従います。
  • 利用明細：課金対象のツールは、応答の末尾に _usage オブジェクトを付けます。呼び出しの費用と残高を示します。詳しくはクレジットと料金をご覧ください。
  • 件数の上限：limit 引数には、サーバー側の上限があります。キーワードの一覧は100件、クラスターは50件です。上限を超える値を指定してもエラーにはならず、上限までの件数を返します。上限を超える一覧は、1ページずつ読み取ります。詳しくは後述の長い一覧を読み取るをご覧ください。
  • 識別子：プロジェクトは project_id、競合サイトは competitor_domain、公開先は destination_id で指定します。いずれも、対応する一覧ツールが返す値です。

長い一覧を読み取る

調査で得られるキーワードは、1回の呼び出しで返しきれない件数になることがあります。そのため一覧系のツールは、1ページずつ返します。ページを返す応答には、そのページの位置を示す3つの項目が入ります。

  • count：この応答に含まれる件数
  • total_matching：ページの取得元となった一覧全体の件数
  • offset：このページに到達するまでに読み飛ばした件数

次のページを読み取るには、offset に limit の値を加えて、同じツールを再度呼び出します。続きがある間は、next_step_suggestion が次に指定すべき offset を示します。エージェントは、手順を指示されなくても一覧をたどれます。count が limit より小さい場合、そのページが最後です。一覧の末尾を超える offset を指定した場合、Kafkaiはエラーを返さず、件数がいくつあるかを示します。

offset を受け付けるツールは決まっています。キーワード、クラスター、被リンク、Search Console、アクセス解析の一覧ツールです。プロジェクト、競合サイト、公開先のように短い一覧を返すツールは受け付けません。

ページごとに1回の呼び出しとなり、そのたびに呼び出し料金がかかります。したがって、100件を1回で読み取るほうが、20件を5回に分けて読み取るより安くなります。長い一覧が必要な場合は、ツールが許す範囲でページを大きく指定し、必要なデータが揃った時点で読み取りを終えます。詳しくはクレジットと料金をご覧ください。

プロジェクトと競合サイト

kafkai_list_projects

プロジェクトの一覧を返します。プロジェクトID、サイトURL、状態、対象地域、キーワード数、競合サイト数が含まれます。多くのツールが project_id を必要とするため、通常はこのツールを最初に呼び出します。

引数：なし

kafkai_get_project_summary

プロジェクトの全体像を返します。サイト情報、ニッチ（専門領域）、対象地域、4C戦略と掲載順位ごとのキーワード数、競合サイトの一覧です。加えて、データの有無を示す3つのブロックが入ります。authority は、対象サイトの強さを各競合サイトと並べたものです。backlinks は、対象サイトと各競合サイトに被リンクデータがあるかどうかと、プロファイル全体の件数です。どの被リンクツールを呼び出すべきかは、このブロックの next_step_suggestion が示します。search_console は、対象サイトのGoogle Search Consoleプロパティを読み取れるかどうか、ドメインの確認状況（domain_verified）、データの対象期間です。読み取れる場合は、next_step_suggestion が2つのSearch Consoleツールを示します。読み取れない場合は、足りない手順（ドメインの確認、または権限の付与）を示します。応答には recommended_strategy も含まれます。機会のもっとも多い戦略を、理由とあわせて示します。last_research は、プロジェクトの直近の調査実行です。全体更新と、競合サイト追加時の調査が対象です。実行中は pending を示します。完了後は結果（success、partial、failed）を示し、失敗があればその理由も示します。

引数：

  • project_id：対象のプロジェクト

kafkai_list_competitors

プロジェクトに登録した競合サイトの一覧を返します。各競合のキーワード数と、調査の status が含まれます。調査に失敗した競合は failed と表示され、理由は error に入ります。その競合のキーワード一覧は不完全です。再試行の方法は、応答の next_step_suggestion が示します。kafkai_update_keywords なら、すべてのドメインを調査し直します。競合サイトを削除して追加し直すなら、競合料金1件分で済みます。キーワード数がもっとも多い top_competitor と、直近の調査実行 last_research も返します。

引数：

  • project_id

kafkai_find_competitors

プロジェクトの対象サイトが検索で競合しているサイトを見つけます。根拠は、対象サイトが実際に順位を持つキーワードです。ホームページの内容からの推測ではありません。Kafkaiは、プロジェクトの国で同じキーワードに順位を持つドメインを集め（トラフィック上位1,000サイトは除外）、双方のキーワード群がどれだけ重なるかで採点します。そのうえで、4Cのツールと同じ勝算（winnability）の基準で対象サイトと比べ、レビューサイト、マーケットプレイス、まとめ記事のメディア、無関係なドメインを除きます。プロジェクトに登録済みの競合サイトには already_tracked が付くため、一覧は「ほかにどのサイトがあるか」として読めます。

各行には、次の値が含まれます。

  • domain、relationship（direct、adjacent。判定できなかった場合は unknown）
  • winnability、rank（0〜1000）
  • intersections（共有するキーワード数）、overlap（その数を双方のキーワード群に対する割合にした値。0〜1）
  • avg_position、etv、keywords_count、sample_keywords、already_tracked

filtered_out は、判定で除いたドメインの数です。site は、対象サイト自身のキーワード数、推定トラフィック、ランクです。行の順序は、直接の競合（direct）が先です。その中では、勝算のあるサイトが巨大なサイトより先で、次に overlap の大きい順です。

行を読むときは、次の2点に注意します。

  • Googleがまだ1つのキーワードにも順位を付けていないサイトは、顧客が行う検索から答えます（method が customer_searches になり、seed_keywords にその検索語が入ります）。それらの検索で1ページ目に出るサイトを、小さいサイトから順に返します。この経路では overlap、etv、keywords_count は空になり、winnability は unknown です。
  • Kafkaiが返すのは候補と根拠です。どれを重視するかの判断は、エージェント側で行います。競合サイトの登録は、別の有料ステップkafkai_add_competitor で行います。

料金は、このツール専用の呼び出し料金です。通常の参照ツールより高くなります。プロジェクトが持つデータを読むのではなく、競合候補、サイトの強さ、判定のデータを新たに取得するためです。行単位の従量分は、ほかの参照ツールと同じです。結果は1日キャッシュするため、同じ条件で呼び出すと同じ一覧を返します。詳しくはクレジットと料金をご覧ください。

引数：

  • project_id
  • limit：返す競合サイトの最大数（既定10、最大20）

kafkai_get_competitor_analysis

競合サイト1件を詳細に分析します。ブランドの説明、競合だけが上位表示されているキーワード（キャッチアップ）、双方が上位表示されているキーワード（競合）を返します。一覧系のツールより基本料金が高くなります。

各キーワードには、前回の計測からの競合の変化として competitor_previous_rank と competitor_rank_change が入ります。また、Competeの行には、対象サイト側の our_previous_rank と our_rank_change も入ります。

引数：

  • project_id
  • competitor_domain：kafkai_list_competitors が返す値
  • include_history：各キーワードに順位の推移を含める場合に指定。競合の順位は competitor_history に、対象サイトも上位表示されている場合は our_history に入ります

キーワード調査（4C戦略）

4つの戦略ツールは、同じ形式のデータを返します。各キーワードには、検索ボリューム、キーワード難易度、CPC、順位、上位ページのタイトルと説明文（該当する場合）、タグ、データの取得時期（first_seen と last_updated）が含まれます。recommended には、ボリュームと難易度から見て着手しやすいキーワードが入ります。

順位には、すべて計測日時が付きます。各キーワードには、前回の計測からの各サイトの変化も含まれます。

  • 対象サイトが上位表示されている場合：our_previous_rank と our_rank_change
  • 競合が上位表示されている場合：competitor_previous_rank と competitor_rank_change

変化が正の値なら、順位が上がったことを示します。Catch-up、Consolidate、Competeでは、include_history も指定できます。指定すると、各キーワードに順位の推移が古い順で付きます。上位表示されている各サイトについて、Kafkaiが記録してきた値です（our_history と competitor_history）。順位が変わらなかった時点は除かれます。「直近3か月で何が動いたか」を知るには、後述の kafkai_get_ranking_changes を使います。

Catch-up、Consolidate、Competeの3つは、対象サイトと競合を比較します。競合を1件も登録していない間は、結果が空になります。一方のComplementは比較しないため、競合の有無にかかわらず使えます。競合を登録せずに掲載順位を確認するには、後述の kafkai_get_ranked_keywords を使います。

4つとも、引数は共通です。

  • project_id
  • limit：返す最大件数（既定20、最大100）
  • offset：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の next_step_suggestion に次の値が入ります。全体の件数は total_matching が示します
  • include_history：Catch-up、Consolidate、Competeのみ。上位表示されている各サイトの順位の推移を含める場合に指定

kafkai_get_catchup_keywords

Catch-up（キャッチアップ）。競合が上位表示され、対象サイトが上位表示されていないキーワードです。コンテンツが不足している領域を示します。どの競合が、どのタイトルで上位表示されているかまでわかるため、エージェントは対象ページを特定したうえで調査に進めます。

kafkai_get_consolidate_keywords

Consolidate（強化）。対象サイトが上位表示され、競合が上位表示されていないキーワードです。すでに成果の出ている領域であり、内容を強化する価値があります。

kafkai_get_compete_keywords

Compete（競合）。対象サイトと競合の双方が上位表示されているキーワードです。双方の順位を返すため、順位差の小さいキーワードから優先的に改善できます。

kafkai_get_complement_keywords

Complement（補完）。対象サイトも競合も、まだ対応していない関連キーワードです。今後追加すべきテーマの候補を示します。複数のテーマから同じキーワードが提案された場合も、返すのは1件だけです。limitは、重複を除いたキーワードの件数になります。

kafkai_get_keyword_clusters

意味的に近いキーワードをまとめたクラスターを返します。1本の記事でまとめて狙えるグループです。各クラスターには、平均検索ボリューム、平均難易度、平均CPC、所属キーワードが含まれます。応答では、ボリュームのもっとも大きいクラスターを推奨します。

引数：

  • project_id
  • limit：返す最大クラスター数（既定10、最大50）
  • offset：読み飛ばすクラスター数。ページ送りに使います（既定0）。続きがある間は、応答の next_step_suggestion に次の値が入ります。全体の件数は total_matching が示します

対象サイトの掲載順位

kafkai_get_ranked_keywords

対象サイトがすでに上位表示されているキーワードと、その順位の変化を返します。これは4C戦略ではありません。4C戦略は競合との比較ですが、このツールは対象サイト自身の順位を直接読み取ります。競合を1件も登録していないプロジェクトでも使えるため、作成直後のプロジェクトで最初に役立ちます。

各キーワードには、現在の順位、前回の順位、前回の計測からの変化、新規に順位がついたかどうかに加えて、検索ボリューム、難易度、CPC、上位表示されているページが含まれます。progress には、上昇・下降・変化なし・新規の件数と、3位以内および10位以内の件数が入ります。

include_history を指定すると、各キーワードにKafkaiが記録してきた順位の推移が、古い順で付きます。推移をグラフにするのに十分な情報です。順位が変わらなかった時点は除かれるため、更新1回につき1点ではなく、変化した時点だけが並びます。

数値を読むときは、次の3点に注意します。

  • ここに出るキーワードは、ConsolidateやCompeteにも出ることがあります。切り出した一部ではなく、掲載順位の全体像です。
  • progress が数えるのは、その呼び出しが返したキーワードだけです。プロジェクト全体の件数は total_ranked_keywords です。
  • 作成直後のプロジェクトには、比較対象となる前回の計測がありません。この場合の変化は、最初に確認した順位からの差です。

kafkai_update_keywords を実行すると、順位が更新されます。各キーワードの推移に次の1点が加わるのも、このときです。

引数：

  • project_id
  • limit：返す最大件数（既定20、最大100）
  • offset：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の next_step_suggestion に次の値が入ります。全体の件数は total_matching が示します
  • include_history：各キーワードの順位の推移を含める場合に指定

順位の変化

kafkai_get_ranking_changes

一定期間に順位が上がった、または下がったキーワードを返します。対象サイト、競合サイト1件、すべての競合サイトのいずれかを指定できます。Kafkaiが計測する順位には、すべて計測日時が付きます。そのため、各キーワードについて期間開始時点の順位と現在の順位を比較できます。結果は、変化の大きい順に並びます。次のような質問に答えるツールです。

  • 直近3か月で何が動いたか
  • この競合はどこで順位を落としているか
  • 失ったキーワードはどれか
  • 競合の順位下落から狙えるキーワードはどれか

各キーワードには movement が入ります。値は次の4種類です。

  • improved：上昇
  • declined：下降
  • new：現在は上位表示されているが、期間開始時点ではされていなかった
  • lost：期間開始時点では上位表示されていたが、現在はされていない

あわせて、次の値が含まれます。

  • current_rank と measured_at：現在の順位と、その計測日時
  • baseline_rank と baseline_measured_at：期間開始時点の順位と、その計測日時
  • rank_change：変化量。正の値なら上昇
  • first_seen：初回確認日
  • 検索ボリューム、難易度、CPC、上位表示されているページ

競合を指定した場合は、competitor_domain と our_rank も付きます。our_rank は、同じキーワードで対象サイトが現在どの順位にいるかです。競合が順位を落としたキーワードのうち、対象サイトがすぐ後ろにいるもの、またはまだ上位表示されていないものは、記事を書く好機です。

summary には、そのサイトで計測したすべてのキーワードの件数が入ります。上昇・下降・変化なし・新規・消失の5つに分けた数です。返したキーワードだけの集計ではありません。変化のなかったキーワードは件数にだけ数え、一覧には含めません。

数値を読むときは、次の3点に注意します。

  • 更新は指示したときだけ実行されるため、「ちょうど90日前」の計測はありません。比較の基準は、期間開始時点以前の最新の計測です。その計測日時が baseline_measured_at です。
  • 期間の途中で計測が始まった場合（period.tracked_since）は、最初の計測を期間開始時点の代わりにします。その初回計測に含まれていたキーワードは、新規とはみなしません。
  • 同じキーワードの行は1つにまとめます。戦略の間を移動したキーワードも、推移は1本につながります。

kafkai_update_keywords を実行すると、順位が更新されます。計測日時付きの次の1点が加わるのも、このときです。

引数：

  • project_id
  • competitor_domain：空なら対象サイトを対象にします。競合のドメイン（kafkai_list_competitors が返す値）なら、その競合です。all なら、すべての競合をまとめて1つの一覧にします。このとき、応答に competitor_domains と by_competitor の内訳が加わります
  • days：期間の日数（既定90、最大365）
  • movement：all（既定。変化なし以外のすべて）、improved、declined、new、lost のいずれか
  • limit：返す最大件数（既定20、最大100）
  • offset：読み飛ばす件数。ページ送りに使います（既定0）。total_matching は movement に一致する件数です。summary は引き続きサイト全体を数えます

被リンク

対象サイトと各競合サイトに、どのサイトからリンクが張られているか、リンク元サイトの強さ、各リンクを最後に確認した日時、サイトごとに獲得・喪失したリンク数の推移を返します。Kafkaiが返すのはデータです。リンク元サイトに共通するテーマや、失われたリンクのうち狙う価値があるものの判断は、エージェント側で行います。

Kafkaiは、被リンクをキーワード調査の一部として取得します。プロジェクトの作成時は対象サイトと各競合サイト、競合サイトの追加時はその競合、kafkai_update_keywords の実行時はすべてのサイトが対象です。以下の3つの参照ツールは、そのスナップショットから応答します。kafkai_update_backlinks は、キーワードを取得し直さずに被リンクだけを更新します。応答には取得日時（as_of）が付きます。未取得のサイトは、空の行を返す代わりに、未取得であることを示します。

対象サイト、または競合サイト1件にリンクしているサイトを返します。リンク元ドメインごとに1行で、そのドメインからのもっとも強いリンクを、強い順に並べます。次のような質問に答えるツールです。

  • 競合Xにリンクしているのはどのサイトか
  • 対象サイトにリンクしているサイトはどれくらい強いか
  • 競合Xが失ったリンクのうち、代わりに獲得できそうなものはどれか

最後の質問には、status に lost を指定します。失われたリンクの各行は、かつて target_page のようなページにリンクし、その後リンクをやめたサイトです。last_seen が、リンクを最後に確認した日時です。

各行には、次の値が含まれます。

  • referring_domain、referring_page、target_page、page_title、anchor
  • link_type、dofollow
  • link_rank、referring_page_rank、referring_domain_rank：0〜1000のスケール。大きいほど強い
  • spam_score、platform_types、country
  • first_seen、last_seen、is_lost、is_new、is_broken、links_from_domain

数値を読むときは、次の2点に注意します。

  • profile には、リンクプロファイル全体の値が入ります。domain_rank、backlinks_total、referring_domains_total、nofollowと切れたリンクの件数、リンク種別・プラットフォーム・国・TLDの内訳です。プロファイルの規模は、この合計値で示します。
  • 行は、その一部の標本です。Kafkaiが保存するのは、最大1,000件のリンク元ドメインからのもっとも強いリンクと、直近1年で失われたリンクのうち強いものです。coverage に、保存した行数と、稼働中リンクの標本が全件かどうかが入ります。「18,452件のうち上位1,000件」のように、全件を見たかのような表現を避けて答えられます。

引数：

  • project_id
  • competitor_domain：空なら対象サイト。競合のドメイン（kafkai_list_competitors が返す値）なら、その競合。1回の呼び出しで1サイト
  • status：live（既定）、lost（直近1年で失われたリンク）、all のいずれか
  • limit：返す最大件数（既定20、最大100）
  • offset：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の next_step_suggestion に次の値が入ります

一定期間に、サイトが獲得・喪失した被リンク数とリンク元ドメイン数を返します。対象サイト、競合サイト1件、またはプロジェクト内の全サイトを並べて指定できます。Kafkaiはサイトごとに、日次の獲得・喪失件数を保持しています（初回取得時から1年分）。期間の値はその合計で、月ごとの内訳も付きます。次のような質問に答えるツールです。

  • 競合Xは直近3か月で何件のリンクを獲得したか
  • 競合のリンク獲得は加速しているか
  • 対象サイトは競合に遅れを取っていないか

サイトごとの行には、次の値が含まれます。

  • status と as_of
  • totals_now：backlinks、referring_domains、domain_rank
  • period_totals：new_backlinks、lost_backlinks、net_backlinks、new_referring_domains、lost_referring_domains、net_referring_domains
  • by_month：月ごとの内訳
  • data_from と data_to：保存している履歴が実際に対象とする日付の範囲

status が ready でないサイトには、まだ件数がありません。

引数：

  • project_id
  • competitor_domain：空なら対象サイト。競合のドメイン（kafkai_list_competitors が返す値）なら、その競合。all なら、対象サイトとすべての競合を1サイト1行で返します
  • days：期間の日数（既定90、最大365）

競合サイトの2つ以上にリンクしていて、対象サイトにはリンクしていないサイトを返します。いわゆるリンクギャップです。リンク元ドメインごとに1行で、強い順に並びます。各行には、各競合サイトに張られているリンクがlinks として付きます。複数の競合サイトにすでにリンクしているサイトは、同じテーマを扱い、同種のサイトへのリンクを受け入れています。そのため、最初にリンクを依頼する候補になります。Kafkaiが返すのは行データです。どのサイトに依頼するか、何を提供するかの判断は、エージェント側で行います。

各行には、次の値が含まれます。

  • referring_domain、competitor_count
  • referring_domain_rank（0〜1000。大きいほど強い）、spam_score、country
  • links：競合サイトごとのリンク（referring_page、target_page、anchor、dofollow、link_rank、last_seen）

応答が対象とした競合サイトは competitors_with_data に入ります。まだデータのない競合サイトは competitors_without_data に入ります。

行を読むときは、次の2点に注意します。

  • 対象サイトの被リンクデータが必要です。「対象サイトにリンクしていない」は、そのデータで判定するためです。競合サイトのデータも、min_competitors 件以上必要です。そろうまでは、不足しているサイトと取得方法を応答で示します。
  • 「対象サイトにリンクしていない」は、保存している対象サイトの稼働中リンクの標本（own_site_coverage。上記の coverage と同じ形式）で判定します。標本の外にあるサイトは、対象サイトにリンクしていても一覧に現れることがあります。

引数：

  • project_id
  • min_competitors：ギャップとみなす条件となる、リンク先の競合サイト数（既定2、最小1）。1 を渡すと、いずれかの競合サイトにリンクしていて対象サイトにはリンクしていないサイトをすべて返します
  • limit：返す最大件数（既定20、最大100）
  • offset：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の next_step_suggestion に次の値が入ります

プロジェクトの対象サイトとすべての競合サイトについて、被リンクデータを取得し直します。リンク元サイトとその強さ、直近1年で失われたリンクと最後に確認した日時、1年分の日次の獲得・喪失件数が対象です。上記3つの参照ツールは、このデータから応答します。

被リンクは、kafkai_create_project、kafkai_add_competitor、kafkai_update_keywords の実行時にも取得します。このツールは、キーワードを取得し直さずに被リンクだけを更新するためのものです。被リンク機能より前に作成したプロジェクト、取得に失敗したあと、1日前のスナップショットでは古すぎる場合に使います。

取得はバックグラウンドで実行し、サイト1件につき1分ほどかかります。直近1日以内に取得したサイトは飛ばします。取得中のサイトを二重に取得することもありません。そのため、続けて2回呼び出しても追加の費用はかかりません。応答には、今回取得するサイト（domains）、飛ばしたサイト（skipped_fresh）、取得中のサイト（in_flight）が入ります。

料金は、実際に取得したサイト1件ごとに、被リンクのみの料金がかかります。キーワードは取得しないため、全体更新より安くなります。詳しくはクレジットと料金をご覧ください。

引数：

  • project_id

ドメイン確認

Kafkaiは、対象サイトの非公開データを、そのドメインを管理していると確認できたアカウントにだけ返します。現在はSearch Consoleの検索クエリ、ページ、クリック数が対象です。今後は他のデータソースも同じ仕組みで扱います。確認には、プロジェクトのドメインのDNSにTXTレコードを1件追加します。レコードは、プロジェクトのホストから登録ドメイン（最上位のドメイン）を求めて、そこに追加します。たとえば blog.example.com のプロジェクトでは example.com に、example.co.jp のプロジェクトでは example.co.jp に追加します（「登録ドメイン」の判定はPublic Suffix Listで行うため、example.co.jp のような2段階の国別サフィックスはそのまま残ります）。1つのレコードで、同じアカウントのすべてのサブドメインプロジェクトに対応できます。レコードの値には、アカウントとドメインの組み合わせごとに固有のコードが入ります。1つのドメインを、2つのアカウント（サイトの所有者と代理店など）がそれぞれ確認することもできます。その場合は、それぞれのレコードを追加します。どちらのツールも無料です。

  1. project_id を指定して、kafkai_verify_domain を呼び出します。応答の dns_record に、追加するレコードが入ります。type は TXT、name はドメイン、value は kafkai-verification= に続くコードです。
  2. そのレコードを、ドメインのDNSプロバイダーで追加します。
  3. kafkai_check_domain_verification を呼び出します。Kafkaiがレコードを照会し、見つかれば status が verified になります。DNSの変更は通常数分で反映されますが、最大48時間かかることがあります。レコードがまだ見つからない場合は、時間をおいて呼び出し直します。

Kafkaiは、確認済みのドメインを定期的に再照会します。レコードを削除すると、元に戻すまでデータを返しません。コードは変わらないため、やり直すのはレコードの追加だけです。

同じレコード、確認ボタン、確認状況は、アカウントのドメインページにもあります。ドメインごとに1件ずつ表示します。エージェントを介さずにブラウザーからレコードをコピーする場合は、このページを使います。どちらの方法でも、ドメインごとのコードは共通です。

kafkai_verify_domain

プロジェクトのドメイン確認を開始し、追加するDNSレコードを返します。確認を開始済みの場合は、同じコードを返します。何度呼び出しても、コードは変わりません。

引数：

  • project_id

応答には、domain（レコードを追加する登録ドメイン）、status（pending または verified）、dns_record（type、name、value）、verified_at、last_checked、last_error、next_step_suggestion が入ります。

kafkai_check_domain_verification

レコードをその場で照会し、kafkai_verify_domain と同じ形式で結果を返します。レコードが見つからない場合、status は pending のままです。照会した値は last_error に入ります。照会に応答がなかった場合（タイムアウト）は、何も変わりません。数分後にもう一度呼び出します。kafkai_verify_domain より先に呼び出しても問題ありません。コードを作成し、追加するレコードを応答に含めます。

引数：

  • project_id

Search Console

対象サイトのGoogle Search Consoleのデータを、2つのツールで読み取ります。順位データが検索結果の標本であるのに対し、こちらはGoogleが対象サイトについて実際に記録した内容です。表示されたすべての検索クエリについて、実際のクリック数、表示回数、クリック率、平均掲載順位がわかります。順位データだけでは答えられない問いに答えます。「何が検索されたか」「どのページがクリックされたか」「何が変わったか」の3つです。

2つのツールは、同じ期間を扱います。保存している最新の28日間と、その直前の28日間を比べます。各行と、プロパティ全体の totals には、直前の期間との差として clicks_change、impressions_change、position_change が付きます。順位が上がったときは、position_change が正の値です。順位ツールと同じ符号です。

データを返すまでに、2つの手順があります。search_console.status が not_connected の間は、どちらのツールも、足りない手順を next_step_suggestion で示します。エージェントは、その手順をそのまま案内できます。

  1. ドメインを確認します。手順は、上の「ドメイン確認」のとおりです。確認前は、Kafkaiはそのドメインについて何も返しません。プロパティがあるかどうかも返しません。
  2. Kafkaiにプロパティの読み取り権限を付与します。Search Console上で1回だけ行い、共有するのはメールアドレス1つだけです。Google Search Consoleでプロパティを開き、設定 > ユーザーと権限 > ユーザーを追加 を開いて、Kafkaiの読み取り用アドレスを入力し、権限に 制限付き を選びます。読み取り用アドレスは、ドメインの確認後に next_step_suggestion に入ります。スクリーンショット付きの手順は、Google Search Consoleを連携するをご覧ください。

次回の調査実行（kafkai_update_keywords）で、Kafkaiがプロパティを検出します。検出後は、履歴を16か月分取り込みます。以降は、調査実行のたびに更新します。最初の同期が終わるまで、ステータスは syncing です。

数値を読むときは、次の2点に注意します。いずれもGoogle側の仕様です。

  • Googleは、匿名化したクエリを省きます。そのため、クエリ行の合計は、プロパティ全体の実数より小さくなります。totals は実数です。coverage には、クエリ行の表示回数（visible_impressions）、実数の合計（total_impressions）、その割合（visible_impressions_share）が入ります。割合は、その呼び出しが返した行を対象に計算します。
  • Google Discoverは、ページと合計だけを報告し、クエリを報告しません。search_type='discover' は、pagesビューとtrendビューでだけ使えます。

kafkai_get_search_console_data

対象サイトが表示された検索クエリ、トラフィックを集めたページ、日別の合計を返します。同じ期間を、3つのビューで見ます。

  • view='queries'（既定）：現在の期間の検索クエリごとに1行です。query、clicks、impressions、ctr、position に加えて、直前の期間の値（prior）と3つの差分が入ります。
  • view='pages'：対象サイトのページごとに1行です。Googleの日別ページ集計（実数）を合計した値です。
  • view='trend'：直前の期間から現在の期間までの、新しい側から数えた1日ごとに1行です。古い順に並ぶため、トラフィックが変わった日がわかります。全期間を一度に取得するには、limit=100 を渡します。

すべての応答に、search_console（property、status、domain_verified）、window、prior_window、totals が入ります。内訳として、totals には current、prior、差分が入ります。併せて、kafkai_get_ranked_keywords も使います。このツールにあって順位データにないクエリは、Kafkaiの標本が取りこぼした実際の検索です。

引数：

  • project_id
  • view：queries（既定）、pages、trend のいずれか
  • order_by：queriesビューの並び順。impressions（既定）、clicks、position（上位から）のいずれか。pagesビューは常に表示回数順です
  • contains：この文字列を含むクエリ（またはページURL）だけを返します。大文字と小文字は区別しません。trendビューには対象がないため、この引数は無視し、応答にも含めません
  • search_type：web（既定）または discover
  • limit：返す最大件数（既定20、最大100）。trendビューでは、新しい日から数えた日数です。limit=100 を渡すと、全期間を一度に返します。両期間の日数は、常に total_matching が示します
  • offset：読み飛ばす件数。ページ送りに使います（既定0）。trendビューでは、最新の日から数えて過去へさかのぼります。続きがある間は、応答の next_step_suggestion に次の値が入ります

kafkai_get_search_console_insights

Search Consoleのデータから、Kafkaiが計算した「最初に取り組むべき点」を返します。指摘は5種類あります。いずれもクエリまたはページ1件です。根拠となる数値（evidence）と、同じ種類の中で順位付けするための score が付きます。

  • striking_distance：1ページ目の少し下（既定では8〜20位）に表示され、表示回数が十分にあるクエリです。scoreは、5位に到達した場合に見込める追加クリック数です。
  • ctr_gap：掲載順位から見込まれる水準を大きく下回るクリック率のクエリです。多くの場合、順位ではなくタイトルやスニペットの問題です。scoreは、失っているクリック数です。
  • cannibalisation：対象サイトの2つ以上のページが表示回数を分け合っているクエリです。scoreは、対象となる表示回数です。
  • new_query：直前の期間にはなく、現在の期間で新たに表示されたクエリです。scoreは表示回数です。
  • decay：直前の期間と比べて、クリック数が大きく落ちたページです。Web検索とGoogle Discoverを別々に計算します。scoreは、失ったクリック数です。

応答の definitions には、各ルールと適用中のしきい値が入ります。種類ごとの件数は counts です。同じ種類の中でだけ、scoreを比較します。種類が違えば、単位も違います。指摘を計算するのはKafkaiです。何を変えるかは、evidence を読んだエージェントが判断します。周辺の行は、kafkai_get_search_console_data で確認できます。

引数：

  • project_id
  • insight_type：all（既定）、または striking_distance、ctr_gap、cannibalisation、new_query、decay のいずれか。all の場合、limit と offset は種類ごとに適用します
  • limit：種類ごとに返す最大件数（既定20、最大100）
  • offset：種類ごとに読み飛ばす件数。ページ送りに使います（既定0）

アナリティクス

対象サイトのアクセス解析データを、1つのツールで読み取ります。Search Consoleが扱うのは検索の側面、つまり何が検索され、どのページがクリックされたかです。アナリティクスは訪問全体を扱います。訪問者数、開かれたページ、訪問のきっかけ、利用環境です。検索データだけでは答えられない問いに答えます。「サイト全体のトラフィックはどれだけあるか」「着いた訪問者は何をするか」の2つです。

データを返すまでに、2つの手順があります。analytics.status ブロック（not_verified、not_configured、unavailable、ready）は、足りない手順をnext_step_suggestion で示します。エージェントは、その手順をそのまま案内できます。

  1. ドメインを確認します。手順は、上の「ドメイン確認」のとおりです。確認前は、Kafkaiはそのドメインについて何も返しません。アナリティクスの設定があるかどうかも返しません。
  2. Kafkaiサポートにトラッキングの設定を依頼します。Kafkaiが管理するアナリティクス環境でトラッキングを設定します。利用者側の作業はありません。設定後の紐付けも不要です。最初の呼び出しで、Kafkaiが対象サイトを自動で見つけて記憶します。設定直後のサイトは、反映まで最長10分かかります。サブドメインのプロジェクトに専用のサイトがない場合は、登録ドメインのサイトを使います。

unavailable は、その呼び出しでKafkaiがアナリティクス環境に接続できなかったことを示します。トラッキングの有無とは関係ありません。1分ほど待ってから、もう一度呼び出します。

Search Consoleと違い、待ち時間はありません。データは呼び出しの時点でライブで読み取るため、ステータスが ready になれば、次の呼び出しからサイトがその時点で持つ値を返します。

kafkai_get_analytics_data

トラフィック、ページ、流入元、訪問者の地域と利用環境を、21のレポートで返します。既定では直近30日間を対象にします。日ごとの時系列には、period='day' と date='last30' を渡します。

すべての応答に、analytics（status、domain_verified、id_site、site_url）、report、レポートの description、適用中の period と date、count、rows が入ります。続きがある間は、応答の next_step_suggestion に次ページの offset が入ります。

引数：

  • project_id
  • report：summary（既定）、pages、entry_pages、exit_pages、page_titles、outlinks、downloads、referrers、search_engines、keywords、social、websites、campaigns、countries、regions、cities、device_types、browsers、browser_versions、operating_systems、screen_resolutions のいずれか。summary は指標1行（訪問数、ユニーク訪問者数、アクション数、直帰率、平均滞在時間）を返します。それ以外は行のリストを返します
  • period：day、week、month、year、range のいずれか。空の場合は range です
  • date：空の場合は直近30日間です。例：today、last30、2024-01-01,2024-01-31（period='range' の場合）
  • segment：訪問を絞り込むセグメント定義。省略できます
  • limit：リスト型レポートの最大件数（既定20、最大100）。summary では無視します
  • offset：読み飛ばす件数。ページ送りに使います（既定0）

kafkai_get_ga_analytics_data

顧客自身のGoogle Analytics 4データ：トラフィック、ページ、ランディングページ、チャネル、流入元/メディア、国、都市、デバイス、ブラウザ、OS、コンバージョンイベント。顧客のGA4プロパティからライブで読み取ります。保存しないため、アクセスを許可すれば同期や待ち時間は不要です。

Search Consoleやアナリティクスと同じドメイン認証ゲートです。ga_analytics.status ブロック（not_verified、not_connected、ambiguous、unavailable、ready）が next_step_suggestion でまだ足りない手順を示します。

  1. ドメインを認証します（上記「ドメイン認証」を参照）。
  2. Google Analyticsで、管理 › プロパティのアクセス管理 › ユーザーを追加と進み、Kafkaiのリーダーアドレスを入力して閲覧者ロールを選択します。次回のツール呼び出しでプロパティが見つかります。リサーチ実行は不要です。

ambiguous は複数のGA4プロパティが同じサイトを主張している状態です。使うプロパティIDをKafkaiサポートにお伝えください。

引数：

  • project_id
  • report：summary（既定）、daily、pages、landing_pages、channels、source_medium、organic_landing_pages、countries、cities、devices、browsers、operating_systems、key_events のいずれか。summary は1行のメトリクス行を返し、それ以外は行のリストを返します。
  • start_date：ISO日付（2026-08-01）またはGA4の相対日付（30daysAgo、yesterday、today）。空の場合は30daysAgo。
  • end_date：ISO日付またはGA4の相対日付。空の場合はyesterday。
  • limit：最大件数（既定20、最大100）。summary では無視します。
  • offset：読み飛ばす件数。ページ送りに使います（既定0）

SERPインテリジェンス

kafkai_get_keyword_serp_data

キーワード1件について、プロジェクト内の情報をすべて返します。上位表示中のドメイン、タイトル、説明文、URL種別、対象サイトの順位、競合の順位、順位の変動、検索ボリューム、難易度、CPC、タグです。応答には ranking_context として、状況の解釈も含まれます。たとえば「競合が3位、対象サイトは圏外。この需要を獲得する記事が必要」という形です。完全一致するキーワードがない場合は、部分一致の候補を返します。基本料金は高めです。

引数：

  • project_id
  • keyword：対象のキーワード（完全一致を優先し、なければ部分一致）

プロジェクト管理

データを変更するツールです。調査は非同期で実行します。実行を指示したあとは作業を続け、kafkai_get_project_summary で結果を確認します。

kafkai_create_project

サイトのプロジェクトを作成し、競合サイトを登録し、キーワード調査全体をキューに登録します。対象サイトと各競合サイトの被リンクも、同じ調査で取得します（被リンクを参照）。料金は調査するサイトの数で決まります。対象サイトの基本料金に、登録する競合サイト1件ごとの競合料金を加えた額です。詳しくはクレジットと料金をご覧ください。

引数：

  • site_url：分析対象のサイト（例：https://example.com）。必須
  • site_name：表示名。省略時はURLを使用
  • description：サイトの簡単な説明
  • location_code：対象とする国の検索結果。必須で、既定値はありません。2のあとにISO 3166-1の数字コードを続けた値です。日本は 2392、マレーシアは 2458、米国は 2840。指定せずに呼び出した場合は課金されずにエラーとなり、選択できる市場の一覧を返します
  • competitors_url：競合サイトURLのリスト。省略可能

競合サイトの登録は必須ではありません。あとから kafkai_add_competitor で追加できます。登録がない場合、Catch-up、Consolidate、Competeは空のままです。いずれも比較する競合が必要なためです。一方でKafkaiは、対象サイトの掲載順位とComplementキーワードを取得します。ドメインと国だけでも、プロジェクトは役に立ちます。

プロジェクトは1つの国に固定されます。対象外の国を調査しても料金は同じで、得られるものはありません。だからKafkaiは推測せず、国を必ず指定させます。

kafkai_add_competitor

既存のプロジェクトに競合サイトを1件追加し、その競合の分だけキーワードと被リンクのデータを取得します。登録済みの競合と対象サイトは再取得しないため、全体更新より費用を抑えられます。かかるのは競合料金1件分です。

調査はバックグラウンドで実行され、全体更新と同じように記録されます。応答には update_log_id が含まれます。数分後に kafkai_list_competitors で確認します。データが揃うと、競合の status は ready になります。失敗した場合は failed になり、理由が error に入ります。調査の実行中は、kafkai_update_keywords と削除ツールを受け付けません。

引数：

  • project_id
  • competitor_url

kafkai_delete_competitor

プロジェクトから競合サイトを1件削除します。その競合について収集したキーワードと、各キーワードの順位の推移も、すべて削除の対象です。誤って追加した競合サイトの無関係なキーワードを、一覧から取り除くときに使います。無料です。

削除は取り消せないため、このツールは2段階で実行します。

  1. confirmation_token を指定せずに呼び出します。この時点では、何も削除されません。応答には、削除される内容と残る内容が含まれます。削除される内容は、戦略ごとのキーワード数、調査セッション、順位の推移です。あわせて、15分間有効なconfirmation_token も返します。
  2. エージェントがその内容を提示し、削除してよいか確認します。承認後に、もう一度呼び出します。このとき、同じ project_id とcompetitor_domain に加えて、confirmation_token を指定します。競合サイトは削除予定の状態になり、データはバックグラウンドで削除されます。数分後に kafkai_list_competitors で、結果を確認します。

トークンは、1つの競合サイトと1つのアカウントに結び付いています。別の競合サイトに使い回した場合や、有効期間を過ぎた場合は、拒否されて何も起こりません。プロジェクトの順位更新が実行中の間は、削除を受け付けません。更新の完了後に、もう一度依頼します。

引数：

  • project_id
  • competitor_domain：kafkai_list_competitors が返すドメイン。ドメインの代わりにURL全体を指定することもできます。
  • confirmation_token：プレビューでは空のままにします。削除を実行するには、プレビューの応答に含まれるトークンを指定します。

kafkai_update_keywords

プロジェクト全体の順位更新をキューに登録します。全戦略と対象サイトの掲載順位を取得し直し、既存キーワードの順位を更新し、圏外になったキーワードに印を付けます。各キーワードの順位の推移に次の1点が加わるのも、この更新です。変化を確認する前に実行します。確認には kafkai_get_ranked_keywords や kafkai_get_ranking_changes を使います。対象サイトとすべての競合サイトの被リンクも、同じ更新で取得し直します（直近1日以内に取得したサイトは再利用します）。料金は作成時と同じ計算です。対象サイトの基本料金に、プロジェクト内の競合サイト1件ごとの競合料金を加えた額です。同時に実行できる調査は、1つのプロジェクトにつき1件です。競合サイト追加時の調査も含めて、実行中の再依頼は拒否されます。削除を確定したプロジェクトも更新できません。この依頼は、課金の前に拒否されます。更新は指示したときだけ実行します。Kafkaiが自動的に順位を再取得することはありません。

引数：

  • project_id

kafkai_delete_project

プロジェクトを、関連データごと削除します。競合サイト、各キーワードと順位の推移、調査セッションがすべて対象です。不要になったプロジェクトや、誤ったサイトで作成したプロジェクトを削除するときに使います。無料です。

削除は取り消せないため、このツールは2段階で実行します。

  1. confirmation_token を指定せずに呼び出します。この時点では、何も削除されません。応答には、削除される内容と残る内容が含まれます。削除される内容は、競合サイト、戦略ごとのキーワード数、調査セッションの数です。あわせて、15分間有効なconfirmation_token も返します。
  2. エージェントがその内容を提示し、削除してよいか確認します。承認後に、もう一度呼び出します。このとき、同じ project_id に加えて、confirmation_token を指定します。プロジェクトは削除中の状態になり、データはバックグラウンドで削除されます。数分後にkafkai_list_projects で、結果を確認します。

トークンは、1つのプロジェクトと1つのアカウントに結び付いています。別のプロジェクトに使い回した場合や、有効期間を過ぎた場合は、拒否されて何も起こりません。公開先のサイトに公開済みの記事は、そのまま残ります。公開先と公開の記録はアカウントに属するため、削除されません。プロジェクトの順位更新が実行中の間は、削除を受け付けません。更新の完了後に、もう一度依頼します。

引数：

  • project_id
  • confirmation_token：プレビューでは空のままにします。削除を実行するには、プレビューの応答に含まれるトークンを指定します。

公開

Kafkaiは記事を書きません。エージェントが上記のデータをもとに記事を書き、完成した本文をKafkaiに渡して公開します。Kafkaiが保持するのは、送信した内容そのもの（タイトル、本文、言語）の記録だけです。記事の別の写しは持ちません。

kafkai_list_publishing_destinations

アカウントに登録した有効な公開先（WordPressサイトとWebhook）の一覧を返します。各公開先の destination_id、名前、種類、URLを含みます。公開先はプロジェクトではなくアカウントに属します。

引数：なし

kafkai_add_publishing_destination

公開先を追加します。WordPressの場合はサイトのURLとアプリケーションパスワードを、Webhookの場合はエンドポイントのURLと認証情報を指定します。認証情報は暗号化して保存し、応答には含めません。

引数：

  • name：公開先の名前（アカウント内で一意）
  • destination_type：wordpress（既定）または webhook
  • url：サイトまたはエンドポイントのURL
  • auth_type：basic（既定）、api_key、bearer、oauth2 のいずれか
  • credentials：認証方式に対応するログイン情報

kafkai_delete_publishing_destination

公開先を削除します。その公開先に公開済みの記事はそのまま残り、公開の記録も保持します。無料です。

引数：

  • destination_id

kafkai_publish_article

エージェントが書いた本文を1つの公開先に公開し、公開先のURL（external_url）を返します。本文はHTMLを content に、またはMarkdownを content_markdown に指定します。content が空の場合はMarkdownをHTMLに変換して送信します。Webhookの公開先にはMarkdownもそのまま渡します。post_status に live を指定しない限り下書きとして公開するため、公開前にサイト上で内容を確認できます。

既存の投稿を更新する場合は、その external_id（以前の公開呼び出しで返された値）を指定してください。新しい投稿を作成せず、既存の投稿が編集されます。

引数：

  • project_id：記事の対象プロジェクト。既定の言語は、このプロジェクトの対象地域から決まります。
  • destination_id：kafkai_list_publishing_destinations が返す値
  • title
  • content：HTMLの本文。content_markdown を指定しない場合は必須
  • content_markdown：Markdownの本文
  • language：en や ja など。既定はプロジェクトの対象地域の言語
  • post_status：draft（既定）または live
  • categories：WordPressのカテゴリ名（例：["Education", "Coffee"]）。存在しないカテゴリは自動作成されます。Webhookの公開先ではそのまま転送されます。
  • slug：投稿のURLスラッグ（例：my-first-article）。Webhookの公開先ではそのまま転送されます。
  • external_id：既存の投稿を更新する場合、その投稿のID。以前の公開呼び出しで返された external_id を使用してください。省略時は新規投稿が作成されます。

クレジット

kafkai_get_credit_balance

現在の残高、累計の購入量と消費量、直近10件の取引を、呼び出しごとの内訳つきで返します。無料です。残高の確認でクレジットを消費することはありません。

クレジットの有効期間は付与日から90日で、古いものから消費されます。expiring には、未使用のクレジットが付与ごとに、利用できる最終日 valid_until とともに期限の近い順で並びます。残りをいつまでに使えばよいか、エージェントが伝えられます。

引数：なし