Search Analytics queries

gsc query runs searchAnalytics.query with every option the API has. The helpers on Search performance are shortcuts for common shapes of this command.

gsc query -s sc-domain:example.com -d query -d page --limit 5000 -o csv
gsc query --last 3m -d date --filter 'country = ind' --filter 'query ~ shoes'
gsc query -d hour --data-state hourly_all --last 2d -o json
gsc query -d query --compare previous --limit 500

Without dates it covers the last 28 days ending at the latest day with data. Google sorts rows by clicks.

DimensionsCopy Anchor Link

-d (--dimension) groups the rows; repeat it or pass a comma list. The columns follow the order you give:

FiltersCopy Anchor Link

--filter 'DIM OP VALUE' filters on query, page, country, device, or searchAppearance; dates come from --start, --end, or --last. Repeated filters are ANDed; the API has no OR.

gsc query -d page --filter 'page =~ ^https://www.example.com/blog/' --filter 'device = MOBILE'
gsc query -d query --filter 'query !~ example'     # leave out branded queries

Search type, data state, and aggregationCopy Anchor Link

• --type: web (default), image, video, news, discover, or googleNews.
• --data-state: final (default), all to include preliminary data, or hourly_all for the hour dimension. See Reading the data.
• --aggregation: auto, byPage, byProperty, or byNewsShowcasePanel. Neither byProperty nor byNewsShowcasePanel can be combined with page grouping or a page filter. byProperty is not available for discover or googleNews; byNewsShowcasePanel needs one of them and exactly one searchAppearance = NEWS_SHOWCASE filter.

These rules are checked before any request is sent. Anything else is left to Google, whose error is shown as it is.

How many rowsCopy Anchor Link

--limit sets the number of rows (default 1,000). Rows are fetched in pages of up to 25,000 with startRow, and --all keeps fetching until Google has nothing more. complete: true in JSON means pagination reached the end of what Google exposes, never that every query is included.

Raw requestsCopy Anchor Link

gsc query -d query --filter 'page ~ /blog/' --print-request      # show the body, send nothing
gsc query --request-file body.json --last 7d                      # start from a body; flags override it
gsc query -d query --raw                                          # Google's response, unchanged

--request-file takes a JSON request body (or - for stdin) for anything flags do not express. --raw prints a single page of Google's response unchanged, so it cannot be combined with --all or --compare.