Diff Tasks

A diff task is one page of a diff batch: the two captures it compares, the score, the verdict, and the diff image.

Read a diff task

endpoint

GET /api/v1/projects/{project_id}/diff-tasks/{diff_task_id}

One diff_task. Minimum key role: Participant. Its id is in the batch's tasks.

The `diff_task` object

diff_task

{
  "object": "diff_task",
  "id": "00000000-0000-0000-0000-000000000008",
  "diff_batch_id": "00000000-0000-0000-0000-000000000004",
  "page": {
    "id": "00000000-0000-0000-0000-000000000007",
    "path": "/pricing",
    "title": "Pricing"
  },
  "status": "DONE",
  "verdict": "FAIL",
  "cancellation_reason": null,
  "error": null,
  "reference_capture_task_id": "00000000-0000-0000-0000-000000000006",
  "candidate_capture_task_id": "00000000-0000-0000-0000-000000000005",
  "compared_by": "pixels",
  "score": {
    "diff_pct": 12.6,
    "match_pct": 87.4,
    "diff_pixels": 503212,
    "tolerated_pixels": 0,
    "pixel_delta_max": 255
  },
  "config": {
    "comparison_tolerance": 0,
    "diff_threshold_pct": 10,
    "max_diff_pixel_count": 100
  },
  "config_sources": {
    "comparison_tolerance": "project",
    "diff_threshold_pct": "page",
    "max_diff_pixel_count": "project"
  },
  "sizes": {
    "reference": {
      "width": 1280,
      "height": 3120
    },
    "candidate": {
      "width": 1280,
      "height": 3160
    },
    "diff": {
      "width": 3840,
      "height": 3164
    }
  },
  "pixel_delta_histogram": {
    "255": 503212
  },
  "diff_image": {
    "url": "https://…",
    "expires_at": "2026-11-06T12:00:00.000Z",
    "bytes": 912004
  },
  "created_at": "2026-11-06T10:02:11.7+00:00",
  "updated_at": "2026-11-06T10:03:40+00:00"
}

Identity and outcome

Field	Type	Value
`diff_batch_id`	uuid string	Its batch.
`page`	object \| null	`id` of the page while it exists, `path` and `title` as when the diff was made.
`status`	string	`PENDING`, `RUNNING`, `DONE`, `CANCELLED` or `ERROR`.
`verdict`	string \| null	`null` while it runs. A page compared is `PASS` or `FAIL`; a page not compared, or whose comparison failed, gets the verdict the environment's verdict config gives its case: `PASS`, `WARN`, `FAIL` or `SKIPPED`.
`cancellation_reason`	string \| null	When `CANCELLED`, why — see below. `null` otherwise.
`error`	object \| null	When the comparison failed: `code` and `message` — see when a page comparison fails. `null` otherwise.
`reference_capture_task_id`	uuid string \| null	The reference capture task; `null` when that side has none.
`candidate_capture_task_id`	uuid string \| null	The candidate capture task; `null` when that side has none.

`cancellation_reason`

A page is not compared when the two sides do not both have a good capture of it. Its verdict comes from the environment's verdict config — see page comparisons.

Value	Meaning
`NEW_PAGE`	The page is in the candidate only.
`REMOVED_PAGE`	The page is in the reference only.
`REFERENCE_ERROR`	The reference capture of the page failed.
`CANDIDATE_ERROR`	The candidate capture of the page failed.
`BOTH_ERROR`	Both captures of the page failed.
`UNIDENTIFIED_PAGE`	A capture's page was deleted, so it cannot be matched across the two sides. Always `SKIPPED`.

The comparison

These are filled in once the comparison has run, and null before, or when it failed or did not run.

Field	Type	Value
`compared_by`	string \| null	`pixels` when the screenshots were compared pixel by pixel; `hash` when they were the same file, byte for byte — 100% match, no diff image.
`score.diff_pct`	number	The share of pixels that differ, from 0 to 100.
`score.match_pct`	number	`100 - diff_pct`, the figure the dashboard shows.
`score.diff_pixels`	number \| null	How many pixels differ.
`score.tolerated_pixels`	number \| null	Pixels that differed within the tolerance, so were not counted.
`score.pixel_delta_max`	number \| null	The largest colour difference of a pixel, from 0 to 255.
`config.comparison_tolerance`	number \| null	The colour difference, 0 to 255, up to which a pixel counts as unchanged.
`config.diff_threshold_pct`	number \| null	Above this `diff_pct`, the page fails. `null`: no such limit.
`config.max_diff_pixel_count`	number \| null	Above this `diff_pixels`, the page fails. `null`: no such limit.
`config_sources`	object \| null	For each of the three settings, where its value came from: `project` (the project's diff config) or `page` (the page's override).
`sizes.reference`, `sizes.candidate`	object	`width` and `height` of each screenshot, in pixels.
`sizes.diff`	object \| null	`width` and `height` of the diff image; `null` without one.
`pixel_delta_histogram`	object \| null	For each colour difference from `"1"` to `"255"`, how many pixels differed by that much. Differences that did not occur are left out: `{}` means no pixel differed.

config is as it was when the page was compared: changing the diff config later does not change it.

The diff image

Field	Type	Value
`diff_image`	object \| null	The diff image; `null` when there is none, as for a `hash` comparison.
`diff_image.url`	string \| null	A signed address to download it from, valid until `expires_at`.
`diff_image.expires_at`	timestamp \| null	When `url` stops working: up to two hours after the call. Trust this date, not a fixed delay.
`diff_image.bytes`	number \| null	Its size, approximately.

As for screenshots, download it while url is valid, or read the task again for a fresh one.