Index of every page on this site: llms.txt
Skip to content

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.

ReportAnalyzersDefault windowComparison
healthctr-anomaly, change-point, position-volatility28dnone
moversmovers, decay, striking-distance7dprev-period
opportunitiesstriking-distance, opportunity, zero-click, query-migration28dnone
risksdecay, cannibalization, dark-traffic, device-gap28dprev-period
growthcontent-velocity, keyword-breadth, intent-atlas, long-tail90dyoy
brandbrand (--brand-terms), concentration28dnone
triagechange-point + query-migration + position-volatility scoped to --target90dnone
pre-publishcannibalization + striking-distance scoped to --topic90dnone

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' --json

Use --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-api
import { 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 failed

Use 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, and triage need complete Store coverage for their required SQL-only Analyzers.
  • Some growth Sections return aggregate summaries instead of per-row findings. The frozen artifact field 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 brand Report's concentration step covers the whole Site.