Compare two audits of a website

What changed between two audits, and the CI gate on new findings

GET/v1/websites/{websiteId}/audits/compare

What changed between two completed audits of one website: findings that are `new`, `resolved`, `worsened`, `improved`, `unchanged`, `still_open`, `not_crawled` or `not_checked`. Without `head` and `base` it compares the website's latest completed audit with the one before it. A finding on a page the newer audit did not crawl (`not_crawled`) or from a rule it did not run (`not_checked`) is neither new nor resolved; `totals` counts them, and `resolutionEvidence` says what backs the `resolved` verdicts (`none` means nothing is reported as fixed). `totals` and `newBySeverity` count every finding; `findings` is clipped by `limit`. **CI gate.** Pass `fail_on` and the response carries `gate`: `status` is `fail` when the newer audit has findings at or above that severity that the previous completed audit did not have, `pass` when it has none, `no_baseline` for the first audit of a website (it passes), and `not_evaluated` when the comparison cannot say (the audit ended `failed` or `blocked`, or a report exceeded the comparison's finding cap). Resolved findings are counted in `gate.resolved` and never fail it, and `gate.notCompared` says how many older findings the newer audit could not judge. A CI job starts the audit with `POST /v1/agent-runs` (send `websiteId`), polls `GET /v1/agent-runs/{id}` until `completed`, then calls this endpoint with `head` set to that run id and exits non-zero on `gate.status: "fail"`. Requires the `audits:read` scope.

Path parameters

websiteIdstringrequired

The website id (`websiteId` on an audit run).

Query parameters

headstring

The newer run id. Default: the website's latest completed run with a report.

basestring

The older run id. Default: the completed run immediately before `head`.

fail_on"error" | "warning" | "info"

Evaluate the CI gate at this severity: `error` fails on new errors only, `warning` on new errors and warnings, `info` on any new finding. Adds `gate` to the response.

Available options: error, warning, info

includestring

Comma-separated extra kinds to list in `findings`: `unchanged`, `still_open`, `not_crawled`, `not_checked`. New, worsened, resolved and improved are always listed.

limitinteger

Most rows in `findings` (default 100). `totals`, `newBySeverity` and `gate` are never clipped.

Responses

The comparison, and the gate when `fail_on` was sent.

comparisonobjectrequired

What changed between two completed audits of a website. Only the fields a CI client needs are listed; others may be present.

gateobject

The CI gate over a comparison, evaluated at `fail_on`.

curl --request GET \
  --url "https://api.squirrelscan.com/v1/websites/WEBSITEID/audits/compare"

const res = await fetch("https://api.squirrelscan.com/v1/websites/WEBSITEID/audits/compare", {
  method: "GET",
});
const data = await res.json();

import requests


r = requests.get("https://api.squirrelscan.com/v1/websites/WEBSITEID/audits/compare")
r.raise_for_status()
data = r.json()

{
  "comparison": {
    "base": {},
    "head": {},
    "firstRun": true,
    "changed": true,
    "totals": {},
    "newBySeverity": {},
    "findings": [],
    "findingsTruncated": true,
    "comparisonIncomplete": true,
    "resolutionEvidence": "page_findings",
    "notes": []
  },
  "gate": {
    "failOn": "error",
    "status": "pass",
    "newAtOrAbove": 123,
    "resolved": 123,
    "notCompared": {
      "notCrawled": 123,
      "notChecked": 123
    },
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

Edit this page