Find the saved crawl snapshot you need

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

Which saved crawl reports are available for this site?

• You need an id for a comparison or focused follow-up.
• Several local crawl snapshots exist.

Command facts

Report id

crawl-history

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, limit

Agent discovery

seo reports describe crawl-history --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• You need the pages and issues inside one saved snapshot. Recommended report: Open a saved crawl report. Open the saved crawl report by id. It loads the report summary and lets you request its page or issue detail without fetching the site again.
• You need to know what changed between two saved snapshots. Recommended report: Compare two saved crawls. Compare the chosen crawl reports. It matches compatible page and issue evidence and separates additions, removals, regressions, and recoveries.

Data sources and inputs

• Local saved crawl metadata. Provides report id, site, generated date, status, page count, issue count, and crawl scope.
• Optional site and result limit. Narrows the list to the project and amount of history needed.

What this report checks

• Reads locally saved report metadata and filters it by the exact optional site.
• Orders snapshots consistently and applies the requested limit without loading report detail.

How it works

• Filters saved metadata by site and returns a stable, limited list.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

List the local crawl snapshots saved for a project. Agents and CI should inspect the live schema before their first run.

seo crawl-reports --project example

seo reports describe crawl-history --json

seo reports run crawl-history --params '{"site":"sc-domain:example.com","limit":10}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "crawl-history"
}

{
  "id": "crawl-history",
  "params": {
    "site": "sc-domain:example.com",
    "limit": 10
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'crawl-history',
  {
  "site": "sc-domain:example.com",
  "limit": 10
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• A compact list of saved crawl ids, sites, dates, status, page totals, issue totals, and configuration metadata.
• Enough context to open one snapshot or choose compatible before and after reports for comparison.
• Choose reports with comparable scope and the right date. Newest is not always the right baseline.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• The list does not inspect the live site or prove that a saved report is complete.

What to do next

1. Open the chosen report.
2. Compare two compatible snapshots when you need change evidence.

Related reports

• Open a saved crawl report. Retrieve one local crawl snapshot in compact form and request its page or issue inventory only when you need it.
• Compare two saved crawls. See which pages and technical issues appeared, disappeared, or changed between two saved crawl snapshots.

Browse all reports in Crawling and technical checks.