---
title: "Build the comparison of two crawls"
method: POST
path: "/v1/sites/{site}/comparison"
tags: ["comparisons"]
---

# Build the comparison of two crawls

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

## Request

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

Queue the build of the comparison of two crawls on the v2 model as a background job (seconds to minutes at 1M URLs), and answer at once. Defaults to the newest accepted v2 crawl against the one before it. The build uses the site's saved URL mapping and Change Detection settings. Repeating is harmless: a rebuild replaces the previous build, which stays readable until it lands. It uses no crawl quota. Next: read comparisons_get with the same pair until its state is built, or changes_get for the pages that came and went.

## Path parameters

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

## Request body

- object
  - `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.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `202`

Build the comparison of two crawls

- 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.
  - `queued` true, required
  - `site_id` string, required: The canonical id of the site.
  - `prev_seq` integer, required
  - `curr_seq` integer, 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`: ORGANIZATION_FROZEN, SCOPE_DENIED
- `404`: SITE_NOT_FOUND
- `409`: AMBIGUOUS_SITE, AGENT_STOPPED
- `503`: PLATFORM_READ_ONLY, 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)