How to Compare ScreenshotAPI Screenshots for Visual Changes

Use ScreenshotAPI’s POST /v1/compare endpoint to compare a freshly rendered page with either a second URL or a named saved baseline. The response includes the percentage of pixels that changed, boxes around changed regions, and a diff image. Supply exactly one of against or baseline. The endpoint applies the same capture parameters to both sides, which helps the images line up.

A changed pixel is evidence to review, not proof of a defect. Pick a threshold that fits your pages and review meaningful changes before accepting them.

1. Choose what to compare

Mode	Parameter	Use it when	What gets rendered
Second URL	against	You want a current comparison, such as a preview deployment against production.	Both URLs are rendered for the comparison.
Saved baseline	baseline	You want to check one page against an image saved under a name, often in CI.	The current page is rendered and compared with the stored image.

Do not send both parameters in one request. The comparison documentation also describes update_baseline, which defaults to false. Use it deliberately when an expected change has been reviewed and should become the new baseline.

2. Compare two URLs with cURL

Set the API key and URLs for your own environment. The example uses the documented endpoint and query fields; include any desired capture parameters supported by the API.

curl -X POST "https://screenshotapi.net/api/v1/compare" \
  -H "Authorization: Bearer $SCREENSHOTAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://preview.example.com",
    "against": "https://www.example.com"
  }'

Store the key in an environment variable or CI secret rather than committing it. The exact authentication and request schema should follow the current ScreenshotAPI endpoint documentation for your account; the research dossier does not include its precise authentication fields or complete schema. Do not assume this illustrative request envelope is a verified vendor example.

3. Compare with a named baseline

Use a stable baseline name for the page and environment. Keep the baseline available across CI runs; a temporary job artifact may disappear before the next comparison.

curl -X POST "https://screenshotapi.net/api/v1/compare" \
  -H "Authorization: Bearer $SCREENSHOTAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://preview.example.com",
    "baseline": "checkout-desktop"
  }'

For an intentional redesign, review the diff first, then use the documented update_baseline option to store the current render as the new reference. Leave it false for ordinary regression checks so that an unexpected render does not silently replace the comparison target. Confirm the precise field format in the vendor documentation before wiring this request into production.

4. Read the comparison result

The documented result provides three useful views:

• Changed-pixel percentage: a compact signal for how much of the image differs.
• Changed-region boxes: locations to inspect in the page.
• Diff image: changed areas are tinted and unchanged areas are faded, making movement easier to spot.

These outputs do not decide whether a difference is acceptable. A timestamp, rotating banner, personalized content, font rendering shift, or asynchronous widget can create visual changes without a product regression. Conversely, a small changed area can contain an important broken control. Use the percentage to route review, then inspect the image and the affected page.

5. Add visual comparison to CI

1. Keep the API key in the CI secret store. Do not put a credential in a checked-in workflow file or log output.
2. Render a stable page state. Use the preview or staging URL after deployment is ready, and make the page deterministic where possible.
3. Compare against a persistent named baseline. Store baseline images where they will remain available across runs; the vendor recommends repository storage because CI artifacts can be temporary.
4. Save the response and diff as CI artifacts. Make the changed percentage and regions visible to reviewers. Follow the API’s documented response fields when parsing the result.
5. Set a project-specific threshold. The vendor describes reporting changes or failing a build above a threshold but does not prescribe a universal acceptable percentage. Start with review-only reporting, observe normal variation, then choose a threshold for your pages.
6. Update baselines intentionally. When a visual change is expected, review it and then update the named baseline in a deliberate change.

ScreenshotAPI documents integrations for GitHub Actions, GitLab CI, and Bitbucket Pipelines, and describes calling the API from a pipeline with cURL or a script. The same workflow applies in other CI systems that can make HTTPS requests.

Example pipeline decision logic

The following is language-neutral pseudocode, not a verified response parser. Map the fields to the current API response before using it:

result = compare(preview_url, baseline_name)

save_artifact(result.diff_image)
report(result.changed_pixel_percentage, result.changed_regions)

if result.changed_pixel_percentage > PROJECT_THRESHOLD:
    require_visual_review()
else:
    continue_build()

For many teams, the first useful check is to publish a report without failing the build. That reveals whether dynamic content or rendering variation makes a hard gate noisy. Add a fail condition only after the team has a reviewed threshold and a reliable baseline process.

6. Keep both sides comparable

Matching capture settings matter because differences in viewport or rendering conditions can look like page changes. ScreenshotAPI says the same capture parameters apply to both sides. Keep these conditions stable across runs as well:

• Use the intended viewport and page state consistently.
• Compare the same locale, content state, and authentication state when the page varies by user or region.
• Wait for the page’s important content to finish loading before capture, if the API exposes an appropriate wait option.
• Reduce animation, rotating content, and time-dependent data in the test environment when you control the page.
• Keep the same baseline name for a given page and viewport; maintain separate baselines when the rendered layouts intentionally differ.

The research dossier does not enumerate every comparison endpoint parameter, so verify the current API reference before relying on a particular wait, viewport, or authentication field.

7. Hosted-renderer access limits

A comparison requires the hosted renderer to reach the page. ScreenshotAPI documents restrictions that include non-HTTP/HTTPS schemes; loopback, private, link-local, carrier-grade NAT, and cloud metadata addresses; hostnames resolving to restricted addresses; embedded URL credentials; and ports other than 80, 443, 8080, and 8443.

This can prevent a private staging site from being rendered as configured. Check the destination’s DNS resolution, scheme, port, and access requirements against the service’s current URL rules. Do not expose a private application publicly just to make a comparison work; use an approved reachable preview environment or another workflow suitable for that application.

8. Quota, reliability, and cost

Each rendered side consumes one quota unit, while the comparison operation itself is documented as free. A URL-to-URL comparison therefore uses two renders; comparing the current page with an existing baseline renders the current page and compares it with the stored image. Failed renders receive their reserved unit back, according to the cited vendor documentation.

The documentation accessed for the research lists monthly quotas of 100 Free, 2,000 Starter, 10,000 Pro, 25,000 Team, and 100,000 Business renders, resetting at the start of each UTC calendar month. These are changeable plan figures; check the current official plan table before budgeting or publishing a quota-dependent workflow.

For quota planning, estimate the number of rendered sides, not just compare operations. For example, one URL-to-URL check per page per CI run uses two render units per page; a current-page check against a saved baseline uses one current render per page. Retries can add attempts, so avoid tight retry loops and report persistent failures clearly.

9. Troubleshooting

Symptom	Likely cause	What to do
The request is rejected before comparison.	Both against and baseline were supplied, or neither was supplied.	Send exactly one reference mode and confirm required fields against the current endpoint documentation.
The renderer cannot load the page.	The destination uses a blocked scheme, address range, port, embedded credentials, or restricted DNS target.	Check the documented hosted-renderer URL restrictions and use a reachable approved target.
The diff shows widespread changes.	The two captures may differ in dimensions, content state, timing, locale, or rendering conditions.	Stabilize the page and use consistent capture settings; inspect the diff before raising the threshold.
Repeated CI runs produce noisy diffs.	Dynamic content, animation, asynchronous assets, or personalized output changes between renders.	Use deterministic test data and a stable page state. If supported, wait for the relevant content before capture.
The baseline comparison cannot find a reference.	The name may not exist, may differ by environment, or its storage may not persist between jobs.	Check the baseline name and persistence strategy; create or update a baseline deliberately after review.
Quota usage is higher than expected.	A URL-to-URL comparison renders two sides, or jobs/retries are running more often than expected.	Count rendered pages per run, limit duplicate jobs, and use the baseline mode when the desired check is one page over time.
A build fails after a visual difference.	The configured project threshold was exceeded; the endpoint does not determine whether the difference is a defect.	Review the changed regions and diff image, then fix the regression or deliberately accept and baseline the expected change.

10. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its single GET request returns a PNG, JPEG, WebP, or PDF. The API can also capture full pages, selected elements, and custom viewports. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status. Its MCP server gives Claude, Cursor, and other MCP clients the tools take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.

Sign up free for 1,000 screenshots a month, with no card required.

Frequently asked questions

Can I compare a preview deployment with production?

Yes. Use the second-URL mode with the preview and production URLs, provided the hosted renderer can reach both destinations.

Does a changed-pixel percentage tell me whether the page is broken?

No. It quantifies visual difference. Review the affected regions to decide whether the change is intended and whether behavior is affected.

Should I update the baseline on every run?

No. Keep the stored reference stable during regression checks. Update it only after reviewing an intentional change.

How many quota units does one comparison use?

A URL-to-URL comparison uses two renders. A comparison against a saved baseline renders the current page, so it uses one render unit, according to the documented quota model.