gsc_performance
Fetch search performance metrics: clicks, impressions, CTR, position. For a site, dimension, or all properties. Set date range or trailing days, data_state for latest data.
Instructions
Search Analytics performance: clicks, impressions, ctr, position.
Three shapes, chosen by what is passed:
No
site-> one row per property the store knows about (scope: "portfolio",sites,totalsaggregated across all of them).site, nodim-> a single aggregate for that site (scope: "site", plusclicks/impressions/ctr/position).siteanddim-> per-dimrows for that site, sorted by clicks descending (scope: <dim>,rows,totalsaggregated acrossrows).dimmust be one of perf.VALID_DIMENSIONS ("query", "page", "country", "device", "date", "searchAppearance").
Date window: pass start_date AND end_date (both "YYYY-MM-DD") for an
explicit range, or leave both unset and get the trailing days calendar
days ending yesterday. start_date without end_date is refused
outright -- {"ok": False, "note": "start_date needs end_date (both YYYY-MM-DD)"} -- rather than guessing an end.
IMPORTANT -- data_state defaults to "all", not Google's own API default
of "final". Passing data_state="final" attaches a warning string
explaining why: data_state='final' silently omits the most recent
~perf.FINAL_LAG_DAYS (3) day(s) of data -- Google has not finished
processing them yet, and nothing in the response marks the gap. The
Search Console web UI has no such restriction and shows those days
immediately, so a 'final' query compared against what a human sees in
the UI right now will look like a discrepancy or a missed traffic
change when both are simply answering different questions. Prefer
data_state='all' (the default here) unless you specifically need
finalized-only rows; its trade-off is that the last day or two may
still revise upward on a later query.
On a missing, expired, or rejected token, returns {"ok": False, "error": "auth_required", "fix": ...}; if no OAuth client is configured at all,
{"ok": False, "error": "not_configured", "fix": ...}. Any other failure
-- a bad dimension, an unroutable site, a Search Console API error --
comes back as {"ok": False, "start", "end", "note": str(exc)} rather
than raising.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dim | No | ||
| days | No | ||
| site | No | ||
| limit | No | ||
| end_date | No | ||
| data_state | No | all | |
| start_date | No | ||
| search_type | No | web |