Capture Batches
A capture batch is a single screenshot run for one environment. It visits every enabled page in that environment using a headless browser and captures a full-page screenshot.
Triggering a capture batch
You can start a capture batch in three ways:
- Manual — click New capture batch from the environment's Capture Batches page.
- Scheduled — configure a recurring interval in the environment's Automation settings. deploydiff will automatically launch a batch when the interval elapses.
- Auto-diff trigger — a capture batch can also be launched automatically as part of the automated diffing workflow (see Environments).
Lifecycle
| Status | Meaning |
|---|---|
| Pending | Created, not yet started |
| Running | At least one page is being captured |
| Done | All pages finished successfully |
| Warning | All pages finished, but at least one page capture errored |
| Error | The batch failed to launch (e.g. domain validation) |
| Cancelled | The batch was cancelled before completion |
What gets captured
For each enabled page in the environment, deploydiff:
- Opens the full URL (environment base URL + page path) in a headless browser.
- Captures a screenshot at the page's configured viewport size.
- Stores the screenshot and generates a thumbnail.
Any custom HTTP headers configured on the environment are sent with every request.
Domain validation
Before capturing screenshots, deploydiff verifies that your organization owns the domain. If this check fails, the batch is marked as errored and no screenshots are taken. See Domain validation for how to set up the verification file and check it before launching a batch.
When a page capture fails
Pages are captured independently: one that fails does not stop the others, and the batch ends in Warning. The failed capture shows an error code and, for most codes, a short message.
| Code | What happened | Charged |
|---|---|---|
NAVIGATION_FAILED | The browser could not reach the page: the domain did not resolve, the connection was refused or dropped, or the certificate was rejected. The message gives the browser's error name. | Yes |
NO_RESPONSE | The navigation ended without a response from the server. | Yes |
UNEXPECTED_STATUS | The page answered with an HTTP status other than 200. | Yes |
PAGE_LOAD_TIMEOUT | The page was still loading after 60 seconds. A capture waits for the network to go quiet, so a page that keeps sending requests — polling, streaming — never gets there. | Yes |
CAPTURE_TIMEOUT | The capture as a whole did not finish within 100 seconds. | Yes |
CUSTOM_HEADER_REFUSED | The browser refused to send one of the environment's custom HTTP headers — a name it reserves, such as Host, or a value it does not accept. The message names the header. | No |
BROWSER_PAGE_ERROR | The page crashed the browser tab while it was being captured, most often by running out of memory. | No |
| Any other code | An internal error on our side. | No |
A capture that fails because of the page is charged for the resources it used, like one that succeeds. The others are not counted in your usage.
Failed captures are not retried. Fix the cause where there is one — the page, the environment's base URL or its headers — and launch a new capture batch. After an internal error, launching a new batch is all there is to do.
In a diff batch, a page whose capture failed is not compared: see page comparisons.
When an embedded frame crashes
A frame embedded from another site — an ad, a video player, a chat widget — runs apart from your page, and can crash on its own, most often by running out of memory. The capture does not fail for it: your page is captured as the browser shows it, with a grey box where the frame was, and the capture names the frame that crashed.
A frame that crashes on some captures and not on others will show up as a difference in your diffs. Mask or hide it in the capture config to keep it out of them.
Relationship to diff batches
A capture batch on its own is a collection of screenshots. Its value comes when compared to another batch via a diff batch. In a diff batch, one capture batch serves as the reference (baseline) and another as the candidate (the new deployment to review).
Usage and billing
Screenshot and thumbnail file sizes captured during a capture batch count towards your organization's storage usage for the current billing period.