---
title: "Two crawls of a site compared, filter by filter"
method: GET
path: "/v1/sites/{site}/comparison"
tags: ["comparisons"]
---

# Two crawls of a site compared, filter by filter

`GET /v1/sites/{site}/comparison`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/sites/{site}/comparison`
- Auth: HTTP bearer

Two crawls of one site side by side: every filter's URL count in the newer and the older crawl with Added, New, Removed and Missing, the URL totals (after URL mapping when the site has one) and Change Detection over the pages present in both. Defaults to the newest accepted v2 crawl against the one before it; an explicit pair may run either way. When `state.status` is not `built`, there is nothing to read yet: call comparisons_start, then read again (a build takes seconds to minutes). A site with fewer than two comparable crawls answers `comparable_crawls` and no pair. For what an agent fixes next (issues appeared, gone, moved), read changes_get.

## Path parameters

- `site` string, required: Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID.

## Query parameters

- `prev_seq` integer: The earlier crawl; omit for the accepted v2 crawl before the current one.
- `curr_seq` integer: The later crawl; omit for the site's newest accepted v2 crawl.
- `limit` integer: Most filters answered (default 100, at most 400); filters with any movement come first.

## Response `200`

Two crawls of a site compared, filter by filter

- union
  - object
    - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
    - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
    - `next_actions` object[], required: What to call next, best first. Follow them.
      - `capability` string, required: What to call next: a capability.
      - `arguments` object, required: Its arguments, complete; pass them as they are.
      - `instruction` string, required: What to do, written to you.
    - `prev_seq` integer, required
    - `curr_seq` integer, required
    - `state` union, required: `none`: never built, call comparisons_start; `building`: read again shortly; `failed`: `error` says why; `built`.
      - object
        - `status` 'none', required
      - object
        - `status` 'building', required
        - `compare_id` string, required
        - `started_at` string, required
        - `waiting_for` string, nullable, required: The heavy read this build waits behind; null while it runs.
      - object
        - `status` 'failed', required
        - `compare_id` string, required
        - `error` string, required: Why the build failed.
        - `finished_at` string, required
        - `last_built_compare_id` string, nullable, required: The build still readable beside the failed one; null when none is.
      - object
        - `status` 'built', required
        - `compare_id` string, required
        - `built_at` string, required
    - `mapping_applied` boolean, required: True: the site's URL mapping rewrote the older crawl's URLs before matching.
    - `totals` object, required
      - `urls_current` integer, required
      - `urls_previous` integer, required
      - `urls_matched` integer, required: URLs present in both crawls (after mapping).
      - `urls_new` integer, required
      - `urls_missing` integer, required
      - `pairs_eligible` integer, required: Matched internal HTML pages: the pages Change Detection looks at.
      - `pairs_with_signatures` integer, required: Of those, pages whose both sides carry a content signature.
    - `filters` object[], required: Filters with any movement first, then by current count; at most `limit`.
      - `key` integer, required: The filter's numeric key: `frontshelf cloud compare --key` takes it for the filter's URLs.
      - `rule_id` string, required: The catalogue check (rules_get takes it); a Change Detection strategy's id for those; an Explorer view's own key (`INTERNAL_HTML`, `RESPONSE_CODE_SUCCESS`) for a `stat` row.
      - `name` string, required: The check as the newer crawl names it, with the threshold that crawl judged by.
      - `prior_name` string, nullable, required: The older crawl's name when the site moved the threshold between the two crawls; null when they agree.
      - `tab` string, required
      - `type` 'issue' | 'warning' | 'opportunity' | 'strategy' | 'stat', required: A catalogue check's type; `stat`: an Explorer view that is not an issue (Internal › HTML, Response codes › Success (2xx)).
      - `priority` 'high' | 'medium' | 'low', nullable, required
      - `current` integer, required: URLs in the filter in the newer crawl.
      - `previous` integer, required: URLs in the filter in the older crawl.
      - `change` integer, required
      - `change_percent` number, required
      - `added` integer, required: URLs in both crawls that entered the filter.
      - `new` integer, required: URLs only in the newer crawl, in the filter.
      - `removed` integer, required: URLs in both crawls that left the filter.
      - `missing` integer, required: URLs only in the older crawl, which were in the filter.
    - `change_detection` object, required: What changed on the pages present in both crawls (title, content, indexability, links, ...).
      - `eligible_pages` integer, required
      - `pages_with_signatures` integer, required
      - `threshold` number, required: The content-similarity threshold a page must fall under to count as changed.
      - `strategies` object[], required
        - `key` integer, required
        - `id` string, required
        - `name` string, required
        - `changed` integer, required: Compared pages this check found changed.
        - `not_changed` integer, required: Compared pages this check found not changed.
        - `not_measured` integer, required: Pages this check could not compare, in neither count: for Content, pages without a text fingerprint on both sides; 0 for every other check. changed + not_changed + not_measured = eligible_pages.
    - `truncated` boolean, required: True when `limit` cut `filters`.
    - `total` integer, required: How many filters the comparison has.
    - `unnamed` integer, required: Filters the comparison counted that no check or view names now (a retired check's frozen key): left out of `filters` and `total`.
    - `provenance` object, required
      - `crawl_seq` integer, nullable, required: The crawl the answer was read from; null when the site has none yet.
      - `data_freshness` string, required: When that crawl finished (ISO 8601) or `no completed crawl`; for a read of one committed crawl, `committed crawl (immutable snapshot)`, or `not committed (<reason>)` when nothing committed answered.
  - object
    - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
    - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
    - `next_actions` object[], required: What to call next, best first. Follow them.
      - `capability` string, required: What to call next: a capability.
      - `arguments` object, required: Its arguments, complete; pass them as they are.
      - `instruction` string, required: What to do, written to you.
    - `prev_seq` integer, required
    - `curr_seq` integer, required
    - `state` union, required: `none`: never built, call comparisons_start; `building`: read again shortly; `failed`: `error` says why; `built`.
      - object
        - `status` 'none', required
      - object
        - `status` 'building', required
        - `compare_id` string, required
        - `started_at` string, required
        - `waiting_for` string, nullable, required: The heavy read this build waits behind; null while it runs.
      - object
        - `status` 'failed', required
        - `compare_id` string, required
        - `error` string, required: Why the build failed.
        - `finished_at` string, required
        - `last_built_compare_id` string, nullable, required: The build still readable beside the failed one; null when none is.
      - object
        - `status` 'built', required
        - `compare_id` string, required
        - `built_at` string, required
    - `provenance` object, required
      - `crawl_seq` integer, nullable, required: The crawl the answer was read from; null when the site has none yet.
      - `data_freshness` string, required: When that crawl finished (ISO 8601) or `no completed crawl`; for a read of one committed crawl, `committed crawl (immutable snapshot)`, or `not committed (<reason>)` when nothing committed answered.
  - object
    - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
    - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
    - `next_actions` object[], required: What to call next, best first. Follow them.
      - `capability` string, required: What to call next: a capability.
      - `arguments` object, required: Its arguments, complete; pass them as they are.
      - `instruction` string, required: What to do, written to you.
    - `comparable_crawls` object[], required: The accepted v2 crawls a pair can be chosen from, newest first.
      - `crawl_seq` integer, required
      - `crawled_at` string, required
      - `pages_crawled` integer, required
    - `state` object, required
      - `status` 'none', required
    - `provenance` object, required
      - `crawl_seq` integer, nullable, required: The crawl the answer was read from; null when the site has none yet.
      - `data_freshness` string, required: When that crawl finished (ISO 8601) or `no completed crawl`; for a read of one committed crawl, `committed crawl (immutable snapshot)`, or `not committed (<reason>)` when nothing committed answered.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `404`: SITE_NOT_FOUND
- `409`: AMBIGUOUS_SITE, COMPARE_VIEW_EXPIRED, AGENT_STOPPED
- `503`: DEPENDENCY_UNAVAILABLE

---

[API](https://skmtc.dev/frontshelf/apis/frontshelf-api.md) · [All operations](https://skmtc.dev/frontshelf/apis/frontshelf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontshelf/apis/frontshelf-api/revisions/ce3602d26c7c?raw)