---
title: "Compare a live site against the snapshot as Site A, at the snapshot’s width and check mode. Every stored page is paired by path onto targetUrl, or urls names the pairs; the job is priced at one captured page per pair it compares, half a live pair, with no discovery, and the free allowance applies as for POST /jobs; a Pro account’s key draws 1 captured page per pair from its allowance. The snapshot’s origin is never fetched, so it may be offline; the DNS guard runs on targetUrl and callbackUrl. The share token goes in Authorization: Bearer dcs_… when nothing pays, or in the X-DiffiCat-Share header beside a paying credential or key. Answers the POST /jobs shape plus snapshotId; the snapshot is unchanged."
method: POST
path: "/snapshots/{id}/compare"
---

# Compare a live site against the snapshot as Site A, at the snapshot’s width and check mode. Every stored page is paired by path onto targetUrl, or urls names the pairs; the job is priced at one captured page per pair it compares, half a live pair, with no discovery, and the free allowance applies as for POST /jobs; a Pro account’s key draws 1 captured page per pair from its allowance. The snapshot’s origin is never fetched, so it may be offline; the DNS guard runs on targetUrl and callbackUrl. The share token goes in Authorization: Bearer dcs_… when nothing pays, or in the X-DiffiCat-Share header beside a paying credential or key. Answers the POST /jobs shape plus snapshotId; the snapshot is unchanged.

`POST /snapshots/{id}/compare`

## Request

- Base URL: `https://app.difficat.com/api/v1`
- URL: `https://app.difficat.com/api/v1/snapshots/{id}/compare`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP payment and API key in header `X-DiffiCat-Share`
  - HTTP bearer and API key in header `X-DiffiCat-Share`

## Path parameters

- `id` string, required

## Request body

- SnapshotCompareRequest
  - `targetUrl` string, uri, required: The live site, Site B.
  - `urls` object[]: Pairs to compare: each source a page of the snapshot (its path, or its full URL on the snapshot’s origin), each target on targetUrl. Without it every stored page is paired by path.
    - `source` string, required: Page URL on Site A.
    - `target` string, required: The same page's URL on Site B.
  - `threshold` number: Visual diff tolerance as a fraction from 0 (exact) to 1: 0.05 means 5%. The web app takes a percentage; the API does not.
  - `maxPriceUsd` number: Optional spend cap in USD. A job priced above it is refused before any challenge, so an auto-paying client is never asked for more.
  - `dryRun` boolean: Quote only: runs every check and the pricing, then answers the page count and exact amount. Nothing is charged, the free allowance is not used and no job starts; the same body without dryRun is priced from the retained result.
  - `callbackUrl` string, uri: Optional https URL (port 443) that receives one JSON POST when the job ends (jobId, status, summary, links; never the jobToken), a nudge to read the job. Public hosts only, no redirects followed, retried twice; delivery never affects the job.

## Response `200`

Dry run: the quote, with nothing charged and no job started

- DryRunResponse
  - `dryRun` true, required
  - `pagesPriced` integer, required: The page count the job would be charged for.
  - `amount` string, required: The exact amount the same body without dryRun is charged.
  - `currency` 'USD', required
  - `allowanceRemaining` integer: For a request with no credential and no prepaid key: the comparison pages the client address may still run free today, read without consuming any.
  - `freeCovers` boolean: For a request with no credential and no prepaid key: true when the same body sent now without dryRun would run free (the priced pages are within allowanceRemaining and the shared daily pool).

## Other responses

- `201`: Job started
- `400`: Invalid input, a blocked callbackUrl, or a pair not in the snapshot
- `402`: Payment required, as for POST /jobs: the free allowance is used up or the request carried a credential
- `404`: No such snapshot, or no access to it
- `409`: The snapshot is still capturing (snapshot_not_ready)
- `429`: The running-job limit or the hourly limit of unpaid requests for this address (Retry-After)
- `500`: The start failed; a settled charge is final
- `503`: Snapshots are not available on this deployment

---

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