Reports
Use Reports to find traffic changes, SEO opportunities, and risks.
gscdump report <id> combines Analyzers into Sections of findings.
The JSON output uses the ReportResult contract.
| Report | Analyzers | Default window | Comparison |
|---|---|---|---|
health | ctr-anomaly, change-point, position-volatility | 28d | none |
movers | movers, decay, striking-distance | 7d | prev-period |
opportunities | striking-distance, opportunity, zero-click, query-migration | 28d | none |
risks | decay, cannibalization, dark-traffic, device-gap | 28d | prev-period |
growth | content-velocity, keyword-breadth, intent-atlas, long-tail | 90d | yoy |
brand | brand (--brand-terms), concentration | 28d | none |
triage | change-point + query-migration + position-volatility scoped to --target | 90d | none |
pre-publish | cannibalization + striking-distance scoped to --topic | 90d | none |
IDs remain stable. Displayed Sections explain what each Analyzer measures:
zero-click: Low-CTR queries. Clicks can be nonzero.content-velocity: Newly observed search queries, first seen within the selected window.intent-atlas: Shared-word query groups. These groups do not classify Search Intent.dark-traffic: Clicks without reported queries. This is an aggregation gap, not a traffic source.keyword-breadth: Search queries per page. Counts do not establish topical authority or ranking vulnerability.
# List Reports
gscdump report list
# Preview a Report without credentials or API calls
gscdump report movers --explain
# Return a Report as JSON
gscdump report opportunities --site example.com --json
# Run Reports with extra inputs
gscdump report triage --site example.com --target /blog/foo --target-kind page --json
gscdump report pre-publish --site example.com --topic widgets --json
gscdump report brand --site example.com --brand-terms 'acme,acme corp' --jsonUse --period for 7d, 28d, 30d, 90d, 180d, 365d, mtd, qtd, ytd, last-quarter, or custom.
Use --vs for none, prev-period, or yoy. yoy compares with the same weekdays 52 weeks earlier.
Windows end on the newest complete date: the newest synced day in the Store, or three days ago (Pacific time) with --live.
Reports with live-capable required Analyzers can use Google when the Site has no Store data. health, growth, and triage need a Store. Partial Store coverage stops with a gscdump sync command.
See Routing.
--start or --end without --period selects a custom window.
Comparison overrides need both --prev-start and --prev-end.
If a live fetch reaches its row budget, the output shows a partial-data warning. --fetch-budget raises the budget up to 100000 rows.
Analyzer, Report, and Section IDs are separate namespaces.
For example, brand names both an Analyzer and a Report.
Programmatic use
Install the Report runtime and live Google API Source:
npm install gscdump @gscdump/analysis @gscdump/engine @gscdump/engine-gsc-apiimport { defaultAnalyzerRegistry } from '@gscdump/analysis/registry'
import { defaultReportRegistry, runReport } from '@gscdump/analysis/report'
import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
import { resolveWindow } from '@gscdump/engine/period'
import { googleSearchConsole } from 'gscdump'
import { getLatestGscDate } from 'gscdump/dates'
const client = googleSearchConsole({ accessToken: process.env.GSC_ACCESS_TOKEN! })
const siteUrl = 'sc-domain:example.com'
const report = defaultReportRegistry.getReport('movers')!
// Anchor windows on the newest complete date, never on today.
const window = resolveWindow({ preset: 'last-7d', anchor: getLatestGscDate(), comparison: 'prev-period' })
const source = createGscApiQuerySource({ client, siteUrl })
const result = await runReport(report, {
source,
analyzers: defaultAnalyzerRegistry,
ctx: { site: siteUrl, window, params: {}, registryVersion: defaultReportRegistry.version },
})
console.log(result.sections)
console.log(result.meta.degraded) // True if an optional step failedUse defineReport() from @gscdump/engine/report to create a Report or adapt an existing one:
import { defaultReportRegistry } from '@gscdump/analysis/report'
import { defineReport } from '@gscdump/engine/report'
export const monthlyMovers = defineReport({
...defaultReportRegistry.getReport('movers')!,
id: 'monthly-movers',
description: 'Traffic changes over the last 30 days.',
defaultPeriod: 'last-30d',
})Data limits:
health,growth, andtriageneed complete Store coverage for their required SQL-only Analyzers.- Some
growthSections return aggregate summaries instead of per-row findings. The frozenartifactfield is an Analyzer reference with its ID and some parameters. It is not a file. Supply the original Site and window when using that reference. - The
brandReport's concentration step covers the whole Site.