Documentation » Connect Google Search Console

Connect Google Search Console

Give Kafkai read access to your Google Search Console property, so that your AI agent can read your actual search queries, clicks, impressions and positions through Kafkai. You add one email address — the Kafkai reader address — as a user of the property. You share no password, and Kafkai cannot change anything in Search Console.

Before you begin

  • You have a Kafkai project for the site.
  • You are an Owner of the Search Console property. Only an owner can add users.
  • The property covers the project's domain:
    • A Domain property (example.com) covers the domain and every subdomain, so it also works for a project on blog.example.com.
    • A URL-prefix property (https://www.example.com/) works only for a project on that exact host.
    • A URL-prefix property with a folder (https://example.com/blog/) matches no project. It reports that folder only.

1. Verify the domain in Kafkai

Open the Domains page in your Kafkai account. Add the TXT record shown on the page to the domain's DNS, then choose Check. You can also ask your agent: "Verify my domain in Kafkai." Verification is free.

Until the domain is verified, Kafkai returns nothing for it — not even whether a Search Console property exists. For more information, see Domain verification in the tool reference.

2. Copy the Kafkai reader address

On the Domains page, copy the Kafkai reader address. The address is the same for every domain and every project. The screenshots on this page hide most of the address, so copy it from your account instead of typing it from an image.

3. Open the user settings of the property

In Google Search Console, select the property. In the menu, choose Settings > Users and permissions.

The Search Console Settings page, with Settings in the menu and the Users and permissions row highlighted

4. Add the reader address with the Restricted permission

Choose Add user. Paste the Kafkai reader address into Email address, set Permission to Restricted, and choose Add.

Restricted is the lowest permission level in Search Console. It lets Kafkai view the data and nothing else. After you add the address, the user list shows it with the Restricted permission:

The Users and permissions list in Search Console, with the Kafkai reader address highlighted and its permission set to Restricted

5. Start a research run

Kafkai does not watch your Search Console account. It looks for the property during a research run, and only you can start a run, because a run uses credits. Ask your agent: "Update the keywords for my project in Kafkai." The agent calls kafkai_update_keywords and tells you the cost before it starts.

During that run, Kafkai finds the property and loads 16 months of history. Each run after that refreshes the data.

Check the connection

Ask your agent: "Is Search Console connected for my Kafkai project?" The agent reads search_console.status from kafkai_get_project_summary:

Status Meaning
not_connected A step is missing. next_step_suggestion names it.
syncing Kafkai found the property and is loading the history.
ready The data is available.

When the status is ready, ask questions such as "Which queries lost clicks in the last 28 days?" For the two tools that read this data, see Search Console in the tool reference.

If the status stays not_connected

  • The domain is not verified. Open the Domains page and choose Check. If the TXT record was removed, access stops until you add the record again.
  • The address has a typing error. Remove the user in Search Console and paste the address again from the Domains page.

Also check that a research run has finished since you added the address, and that the property type covers the project's host.

Remove the access

To stop Kafkai from reading the property, open Settings > Users and permissions in Search Console, open the menu on the row of the reader address, and choose Remove access. Kafkai can no longer read the property from that moment.