PagePeeker Screenshot API Returns a Blank Image: Fixes

If the PagePeeker screenshot API returns a blank image, first confirm that your request uses the current V2 endpoint and that the target URL is encoded correctly. Then inspect the response headers and the readiness endpoint: a thumbnail that is still pending differs from one whose creation returned an error. Finally, check whether you are seeing a cached capture. PagePeeker documents V2 as its recommended API; its original V1 API is discontinued and redirects to V2. PagePeeker API documentation.

1. Confirm the endpoint and request

PagePeeker documents the direct-link endpoint as /{entrypoint}/v2/thumbs.php. The target URL must be URL encoded as a parameter. Check that your integration is not still calling the discontinued V1 endpoint.

PagePeeker documents sizes from tiny (90 × 68) through extra-large (480 × 360); additional sizes may be available on premium accounts. Verify that the size you request is valid for your account. The source documentation does not establish invalid size as a general cause of blank captures, so treat this as request validation rather than a guaranteed fix.

curl --get 'https://PAGEPEEKER_ENTRYPOINT/v2/thumbs.php' \
  --data-urlencode 'size=large' \
  --data-urlencode 'url=https://example.com/page?campaign=spring&view=full' \
  --output pagepeeker-thumbnail.jpg

Replace PAGEPEEKER_ENTRYPOINT with the entrypoint provided for your PagePeeker account, and use a documented size available to that account. Do not log or share secret account credentials.

2. Inspect the response and capture evidence

For paid and unbranded accounts, PagePeeker documents these capture response headers:

• X-PP-Error: whether there was an error creating the thumbnail.
• X-PP-Final-URL: the URL reached after redirects.
• X-PP-Capture-Method and X-PP-Capture-Time: capture method and capture time.
• X-PP-Hash and X-PP-Timestamp: capture identification and timestamp values.

These headers are documented for paid and unbranded accounts. Their absence on another account type does not by itself show that capture failed. Record the HTTP status, request parameters (excluding secrets), and any returned X-PP-* headers before changing your integration.

curl --silent --show-error --dump-header response-headers.txt \
  --get 'https://PAGEPEEKER_ENTRYPOINT/v2/thumbs.php' \
  --data-urlencode 'size=large' \
  --data-urlencode 'url=https://example.com/page' \
  --output pagepeeker-thumbnail.jpg

Review response-headers.txt. In particular, check X-PP-Error and whether X-PP-Final-URL points somewhere unexpected. A redirect to a login, challenge, or error page can explain why the resulting image does not look like the requested page, but the PagePeeker documentation reviewed does not enumerate every possible capture cause.

3. Check whether the thumbnail is ready

PagePeeker documents a readiness endpoint named thumbs_ready.php. Its JSON has separate Error and IsReady fields:

• IsReady: 0 means the thumbnail is not available yet. This is pending work, not automatically a creation error.
• Error: 1 means an error was reported while creating the thumbnail.
• IsReady: 1 means the thumbnail is available.

Use the readiness URL and parameters specified by the current PagePeeker documentation for your account and entrypoint. A typical diagnostic sequence is to request readiness, wait if it is not ready, and request the thumbnail once available. Do not infer that a placeholder image proves the capture process finished successfully.

curl --get 'https://PAGEPEEKER_ENTRYPOINT/v2/thumbs_ready.php' \
  --data-urlencode 'size=large' \
  --data-urlencode 'url=https://example.com/page'

Inspect the returned JSON rather than treating every response as an image. PagePeeker also documents a wait option that can wait up to a given maximum before returning a generated thumbnail or placeholder. This option is premium-only; confirm its supported value and request format in the vendor documentation before using it.

4. Account for cached thumbnails

PagePeeker says thumbnails are cached on its servers for several days. Repeating a display request may return the existing capture rather than create a fresh one. PagePeeker distinguishes an API call from a render: calls can occur when displaying an existing thumbnail, generating an uncached one, checking readiness, or using an exposed API.

If the page changed and you need a new capture, determine whether the current result is simply stale. PagePeeker documents refresh=1 as a premium-only regeneration option. Use it only if your account supports it and you actually need a new render. The stated several-day cache period is not a guaranteed expiry for every URL or account.

5. Check whether the target site permits capture

PagePeeker says its capture robot attempts to fetch a site only once every 5–7 days to minimize traffic. A site owner can opt out using the documented robots.txt rule:

User-agent: PagePeeker
Disallow: /

If you control the site, inspect its robots.txt and access behavior. If you do not, ask the site owner whether automated capture is allowed. This rule is an opt-out signal to investigate; it is not proof that robots rules caused a particular blank image.

More generally, screenshot automation can encounter CAPTCHA pages, access-denied responses, or other automation blocks. Browserless describes these as possible explanations for blank or white screenshots in its own guidance. That is general screenshot-API context, not evidence that PagePeeker exposes the same diagnostics or has the same remedies. Browserless troubleshooting guidance.

6. Troubleshooting by symptom

Symptom	What to check	Next step
Old integration still uses V1	Inspect the endpoint path.	Move to the documented V2 endpoint; V1 is discontinued and redirects to V2.
Request produces an unexpected or unusable result	Check URL encoding, requested size, HTTP status, and—when available—X-PP-Final-URL.	Correct the request and investigate redirects or the final destination.
Readiness says IsReady: 0	Check whether Error is also set and query readiness again according to your integration’s retry policy.	Treat it as pending unless the error field reports a creation error. Premium accounts can check the documented wait option.
Readiness reports Error: 1	Save the JSON, HTTP status, request, and available capture headers.	Share the evidence with PagePeeker support; the public documentation does not give a complete cause-to-remedy table.
Image is valid but stale	Consider the documented several-day cache and whether a new render is actually needed.	Use refresh=1 only if your account supports the premium option.
Blank or challenge-like page	Check the final URL and ask the site owner whether the capture robot is allowed.	Investigate redirects, opt-out rules, or access restrictions without assuming a specific cause from the image alone.
Expected capture headers are missing	Check whether the account is paid or unbranded.	Those headers are documented for those account types; collect the status and readiness JSON as well.

7. Escalate with a useful diagnostic bundle

If the request remains blank or reports an error, send PagePeeker a compact, reproducible report. Include:

• The target URL and request endpoint/parameters, with API secrets removed.
• The approximate request timestamp and HTTP response status.
• Returned X-PP-* headers, if your account exposes them.
• The complete readiness JSON, including Error and IsReady.
• Whether the result appears stale, whether a refresh was requested, and whether the account supports premium controls.

This bundle uses the diagnostic fields PagePeeker documents. It does not imply a guaranteed remedy or support response time.

Or skip the browser setup

If you need a screenshot endpoint with explicit handling for common capture noise, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request can return PNG, JPEG, WebP, or PDF; see the API documentation.

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 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 response headers report the page verdict and billing status. Its MCP server provides screenshot, page-info, and PDF tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

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

FAQ

Does a blank thumbnail always mean the PagePeeker capture failed?

No. Check readiness and the documented error field. A pending result, cached result, redirect, or target-site access issue can require different investigation.

Will requesting the thumbnail again force a new render?

Not necessarily. PagePeeker says thumbnails are cached for several days; its documented refresh=1 regeneration option is premium-only.

Can every PagePeeker account use wait and refresh?

No. The documentation identifies both controls as premium-only. Confirm account access and current parameter requirements in the official API documentation.

What should I redact before sharing a request?

Remove API keys and other secrets. Preserve the target URL, non-secret parameters, response status, timestamp, available capture headers, and readiness JSON so the request can be diagnosed.