Google Search Console

The Search Console connector is a scheduled, read-only sync against the Search Console API's searchAnalytics/query endpoint. For each site you connect, a background worker fetches daily performance rows, verifies and normalizes them, and stores daily aggregates. URL-prefix and domain (sc-domain:) properties are both supported. It never changes your Search Console settings, sitemaps, or verification.

Connecting Search Console requests exactly one OAuth scope:

https://www.googleapis.com/auth/webmasters.readonly

That grants read access to Search Console data for sites your Google account can see. SyncingBeam uses it for two things only: listing your verified sites during setup, and querying search performance. We never request:

• the read-write Search Console scope (we cannot submit sitemaps, change settings, or add/remove sites or users);
• any other Google API scope — connecting Search Console grants nothing about Analytics, and vice versa;
• Google sign-in scopes (openid, email, profile) as part of this connection — signing in to SyncingBeam is a separate step that grants no access to your Search Console data.

The full data-handling policy, including the Limited Use disclosure, retention, and deletion, is on the security page.

Every stored row is one calendar day × one dimension value, keyed by client, connector, date, dimension, and dimension key. The dimensions fetched (each can be turned off per connector on request):

• total — the site-wide daily line;
• device — desktop / mobile / tablet;
• country;
• query — the search terms Google reports;
• page — landing URLs, with query strings stripped before storage.

Metrics per row: clicks, impressions, and position. Position is stored as an impression-weighted sum plus the number of impression samples, so average position stays mathematically exact when days or dimension values are rolled up — not an average of averages.

Freshness and windows: the newest day fetched is two days behind today, matching Search Console's own finalization delay, and each sync re-fetches a trailing 4-day window so late adjustments from Google replace what was stored. Backfills reach back at most 16 months from the newest available day, which is as far back as Search Console itself keeps data. They are scheduled one calendar month at a time, so an interrupted backfill resumes at the first month not yet stored.

Within each range, query and page detail is requested one day at a time, because Google can limit multi-day detail responses even when they look complete. The total, device, and country dimensions are requested in calendar-month ranges. Every request pages through results in pages of up to 25,000 rows.

• 16-month horizon. Search Console keeps roughly 16 months of performance data; the connector's backfill floor matches it. Older data is gone at the source and cannot be reconstructed. Data SyncingBeam has already stored stays yours as the source window rolls forward, so connecting early builds a longer history.
• Anonymized queries. Google omits rare and privacy-filtered queries from the API, so per-query rows sum to less than the site totals. The total dimension is fetched separately for this reason and is the number to trust for site-wide trends.
• Two-day lag. Data for yesterday and today is never fetched; the newest stored day is two days old, by design.
• Row limits. Google exposes at most 50,000 rows per day for each dimension. For query detail a day at that ceiling is stored as returned, because no request can read past it; very large sites may also see Google return a shorter long tail than exists, which SyncingBeam flags as possibly truncated rather than presenting as complete. For the other dimensions, a monthly range that would exceed 100,000 rows is split in half and re-read until each piece fits, so nothing is dropped. Only a single day with more than 50,000 rows for page, device, country, or total cannot be read completely, and that stops the sync with an error instead of silently importing a truncated tail.
• Daily grain only. No hourly data, and no per-search-appearance or fresh (less-than-48h) data.

1. Sign in to SyncingBeam with any of the options on the sign-in screen. Signing in does not connect any Google data yet.
2. Open the client's Settings page and find the Data sources section (organization owners and admins only).
3. Click Connect Search Console. You are redirected to Google's consent screen, which lists exactly one permission: read-only access to your Search Console data.
4. Approve, and you are returned to Settings where SyncingBeam lists the sites your Google account can access, with the permission level Google reports for each. Pick the site for this client — domain properties (sc-domain:) included.
5. Daily syncs begin automatically, and a backfill can pull up to 16 months of history.

Unverified-app warning: until Google's OAuth verification of SyncingBeam completes, Google may show a "Google hasn't verified this app" warning during step 3. The requested scope is the same either way (one read-only scope), and you can inspect it on that screen before approving.

• "Authorization failed" / permission denied. Google returned 401/403: the connected Google account is not a user on that Search Console property, or its grant was revoked. This is treated as permanent. Have the site owner add the account in Search Console, then reconnect from Settings.
• Access revoked at Google. You can revoke SyncingBeam anytime at myaccount.google.com/permissions; syncs then stop with an authorization error until you reconnect.
• Rate limits and outages. On 429 the job defers, honoring Google's Retry-After header when present (clamped between 1 second and 1 hour); on 5xx or timeouts it retries with exponential backoff capped at 15 minutes, for up to 5 attempts before the job is parked for operator attention.
• "Partition reached the configured row cap" or "daily page cap reached." A single day held more rows than Google lets any request read for one dimension. In practice this is the page dimension on a very large site. Monthly ranges are split automatically, so this only happens at the single-day level. The sync stops with an error instead of importing a silently truncated tail, and retrying will not change the result. To recover, email [email protected] with the client name: we can stop collecting the page dimension for that site (the dimensions are configured per connector) so the remaining dimensions keep syncing.
• Connection check. Connecting runs a one-row test query first, so a bad site URL or missing access surfaces immediately rather than at the first scheduled sync.

• Repo: web/src/lib/google-oauth.ts (exact scope, consent URL, site listing), packages/backend/src/connectors/gsc.ts (dimensions, windows, 16-month floor, caps), packages/backend/src/connectors/google-search-console-gateway.ts (API endpoint, error handling), packages/backend/src/db/schema/analytics.ts (stored grain), packages/backend/src/ingestion/queue.ts and errors.ts (retry/deferral).
• Search Console API, searchanalytics.query reference — developers.google.com/webmaster-tools/v1/searchanalytics/query (accessed 2026-07-16).
• Search Console performance report (data retention, anonymized queries) — support.google.com/webmasters/answer/7576553 (accessed 2026-07-16).
• Search Console API usage limits — developers.google.com/webmaster-tools/limits (accessed 2026-07-16).
• Unverified-app warning — support.google.com/cloud/answer/7454865 (accessed 2026-07-16).
• SyncingBeam security & Google data page (scopes, Limited Use, disconnect and deletion).