---
title: "Reports"
description: "Run gscdump Reports with date windows, comparisons, and the inputs each Report requires."
canonical_url: "https://gscdump.com/gscdump-cli/api/reports"
last_updated: "2026-10-03T07:15:31.531Z"
---

# Reports

`gscdump report <id>` combines Analyzers into a `ReportResult` with Sections of findings.

::table{tabindex="0"}
| 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        |
::

::pre{tabindex="0"}
```bash
# 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](/gscdump-cli/api/query#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:

::pre{tabindex="0"}
```bash
npm install gscdump @gscdump/analysis @gscdump/engine @gscdump/engine-gsc-api
```
::

::pre{tabindex="0"}
```ts
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:

::pre{tabindex="0"}
```ts
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. Use `artifact.analyzer` to inspect their data.
- The `brand` Report's concentration step covers the whole Site.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.