# Search Console

Google removes the search query from the referrer, so a site never sees what an organic visitor typed. Google Search
Console still reports the queries behind your clicks, per page, day, country and device. Connect it and every organic
Google session in HQ shows **Likely searches**: the searches that brought clicks to that session's landing page on
that day.

## Connect

You need the Owner or Admin role on the site, and a Google account that can read the site in
[Search Console](https://search.google.com/search-console).

1. Open **Sites › your site › Settings › Search Console** and choose **Connect Google Search Console**.
2. Sign in to Google and allow **View Search Console data for your verified sites**. That is the only permission
   Double Agent asks for. It is read-only.
3. Back in Settings, pick the property for this site. Only properties that cover one of the site's verified domains
   are offered: a domain property (`sc-domain:example.com`, which covers its subdomains) or a URL-prefix property
   (`https://www.example.com/`).

The first import starts within the hour. It brings in the last 90 days, newest first, then updates once a day.
Search Console publishes a day's data 2 to 3 days later, so the newest sessions show *check back then* for a while.

| Status | Meaning |
|---|---|
| Importing | Data is up to date or catching up. |
| Pick a property | Google is connected; choose the property. |
| Import failing | The last import failed and is retried every hour. The error says why. |
| Connect again | Google refused the stored access: it was revoked, the password changed, or the account lost access. Connect again. |

**Disconnect** revokes Double Agent's Google access and deletes the imported search data for the site. Deleting the
site does the same, except that the Google permission stays in your Google account until you remove it at
[myaccount.google.com/permissions](https://myaccount.google.com/permissions).

## What "likely" means

Search Console reports totals, never individual visitors. For a session from Google search, Double Agent looks up
its landing page on its day and lists the top 5 queries by clicks:

- **Same country and device**: rows for the session's country and device type (desktop, mobile or tablet).
- **All countries and devices**: when no row matches the session's country and device, the page's rows for that day
  are used instead, and the session says so.

One of these is probably what the visitor searched, but none is certain to be. A page with many queries spreads
its clicks over all of them. Days follow Search Console, which counts in Pacific Time.

Only Google web search counts. Ads clicks (a `gclid`), Bing, other search engines and Google's other products
(Gmail, Gemini) show no likely searches. Search Console leaves out rare queries to protect searchers' privacy, so
some pages show none even when they get clicks.

## Privacy

- Search Console data is aggregated by Google: query, page, country, device and day, with click counts. It holds
  no visitor identifiers, and Double Agent never links a query to a person. It is shown on a session only as a
  likely match for its page and day.
- Only rows with at least one click are stored. They are kept for 90 days, like session detail, and deleted when you
  disconnect or delete the site.
- The Google access token is stored encrypted and used only to read your Search Console performance report. Double
  Agent never writes to Search Console.
- Connecting, choosing a property and disconnecting appear in the site's audit log.

## API

Members with access to the site's data can read the same answer:

```http
GET /v1/sessions/{sid}/searches?site=st_…
```

```json
{
  "status": "ok",
  "match": "exact",
  "date": "2026-10-01",
  "page": "/pricing",
  "country": "usa",
  "device": "MOBILE",
  "property": "sc-domain:example.com",
  "searches": [{ "query": "acme pricing", "clicks": 9 }, { "query": "acme plans", "clicks": 4 }]
}
```

`match` is `exact` (same country and device) or `page_day` (all countries and devices). Without results, `status`
says why: `not_google_organic`, `not_connected`, `pending` (Search Console has not reported that day yet), `no_data`
or `unavailable`.