Thumbalizr Not Capturing a Page with Cloudflare: What to Check

If Thumbalizr is not capturing a Cloudflare-protected page, first inspect the response headers. X-Thumbalizr-Status tells you whether the request is queued, completed, or failed; X-Thumbalizr-Error gives a failure reason. If the status is OK but the image shows a Cloudflare challenge, Thumbalizr completed the capture, but the page it received was challenge content. That alone does not prove why Cloudflare showed it.

Work through the checks below in order. They separate a pending job, a malformed or unsupported request, a challenge response, and a site-side block. Thumbalizr’s documentation does not establish a universal Cloudflare fix or a Thumbalizr-specific allowlisting recipe.

1. Read Thumbalizr’s status and error headers

Start with the HTTP response from the Thumbalizr API. Its API documents three status values:

Header value	What it means	What to do
`QUEUED`	The capture is still waiting to be processed.	Wait and retrieve or inspect the result according to the request flow you use. Do not diagnose a Cloudflare block from a job that has not finished.
`OK`	The capture completed successfully at the API level.	Open the image. If it contains a challenge, denial, or unexpected page, investigate what the target returned.
`FAILED`	The capture failed.	Read `X-Thumbalizr-Error` and preserve its exact value for troubleshooting or support.

These are Thumbalizr’s documented statuses; they do not identify Cloudflare as the cause by themselves. The error header is documented as the reason the screenshot failed. Thumbalizr API Documentation.

Inspect headers with cURL

Use the endpoint and authentication format from your Thumbalizr account or integration. The command below requests response headers as well as the response body; replace the placeholders and parameters with the ones in your actual request.

curl -i -G 'THUMBALIZR_API_ENDPOINT' \
  --data-urlencode 'url=https://example.com/page?x=1&y=two' \
  --data-urlencode 'YOUR_AUTH_PARAMETER=YOUR_API_KEY'

Look for X-Thumbalizr-Status and X-Thumbalizr-Error. The endpoint and authentication parameter above are placeholders: use Thumbalizr’s current API documentation for the exact request URL and account credentials.

2. Verify the URL and capture settings

Thumbalizr explicitly calls out correct parameter encoding, especially for the target url. Query strings, ampersands, fragments, and other reserved characters can be corrupted if the URL is assembled manually. Encode the complete target URL as a parameter value, and check that the decoded value is exactly the page you meant to capture.

Also verify that the requested options are available to your account. Thumbalizr documents browser width and height, screenshot size, delay, and browser country; availability varies by account tier. An unsupported or unavailable setting can make a request behave differently from the configuration you intended. Consult the API documentation and feature and account information.

Confirm the scheme is present, such as https://.
Check that the URL has not been double-encoded or truncated at an ampersand.
Temporarily remove optional settings and retry with a minimal request.
Then add viewport, size, delay, and country settings back one at a time.
Use only settings enabled for your account tier.

3. Check what the captured page actually contains

Compare the screenshot with an ordinary browser visit to the same URL. Note whether the normal visit shows the expected page, a challenge, an access denial, or content that changes by region. A capture service can receive different content from your browser because the request context may differ. This is a diagnostic possibility, not a confirmed explanation for a particular Thumbalizr result.

Cloudflare documents that automated browser traffic can be identified as bot traffic. Its Browser Run screenshot documentation also says that changing the userAgent does not bypass bot protection. That statement describes Cloudflare Browser Run, not Thumbalizr’s request identity, and it is not a reason to try to evade a site’s protections. See Cloudflare’s screenshot documentation and Browser Run FAQ.

If the image shows a challenge, record the visible result and timestamp. If it shows the normal page but appears stale or incomplete, check the requested delay and other capture settings before concluding the request was blocked.

4. If you administer the protected site, inspect Cloudflare events

When you control the target domain, inspect Cloudflare’s security events and the rule that acted on the request at the time of the capture. Use the event details to determine whether the request was challenged, blocked, or allowed, and which rule applied. Share the timestamp and relevant request details with your capture provider if you need help identifying the traffic.

Cloudflare’s published allowlisting instructions in the reviewed Browser Run material apply to Browser Run. Do not copy a Browser Run identifier or rule and assume it applies to Thumbalizr. Any change to your site’s security policy should be based on the event you observed and your site’s access requirements.

5. Separate the two common cases

Your situation	Useful checks	What you can conclude
You do not control the protected site	Thumbalizr status and error headers, URL encoding, account-supported settings, and the rendered screenshot.	You can identify whether the API failed or captured challenge content. You generally cannot change the site’s Cloudflare rules; send useful evidence to the site owner or Thumbalizr support.
You control the protected site	All request checks above, plus Cloudflare security events and the rule that matched.	Site-side event evidence can support a diagnosis. Do not assume a Browser Run-specific allowlisting method applies to Thumbalizr.

6. Gather evidence before contacting support

A concise incident report makes the result easier to diagnose. Include:

The target URL, with secrets and sensitive query values removed.
The capture time and timezone.
The exact X-Thumbalizr-Status and X-Thumbalizr-Error values.
The screenshot or a description of its contents: expected page, challenge, denial, blank page, or partial page.
The requested viewport, screenshot size, delay, browser country, and other settings.
Whether you control the target site and, if so, the relevant Cloudflare event or rule details.

Do not send API keys, session cookies, authorization headers, or other credentials in a support ticket unless the provider gives you a secure method and specifically needs them.

Common errors and fixes

Symptom	Likely area to check	Next step
Status is `QUEUED`	Processing is not complete.	Wait for completion and inspect the final status before diagnosing the image.
Status is `FAILED`	The capture failed; the API may give a reason.	Copy `X-Thumbalizr-Error` exactly and address that reported issue.
Status is `OK`, but the image is a challenge	The capture completed and the target returned challenge content.	Compare with a browser visit; if you administer the site, inspect the security events for the capture time.
Wrong page or query-string variant	URL encoding or truncation, often around reserved characters.	Encode the entire target URL as one parameter and verify the decoded destination.
Settings seem ignored or the request fails after adding options	An option may not be available for the account tier or may be malformed.	Retry with a minimal request, then add supported settings one at a time.
Browser and capture show different regional content	Region-dependent content or a different request context.	Check the configured browser country if available on your tier and compare the rendered results. Treat this as a hypothesis until evidence confirms it.

Performance, reliability, and cost considerations

For diagnosis, change one variable per retry and keep the target URL, timestamp, settings, headers, and resulting image together. This helps distinguish a request-format issue from a region or site-security response. A longer delay may help when the page itself needs time to render, but it cannot establish that a Cloudflare challenge will be passed.

Interpret API completion separately from page correctness: OK means Thumbalizr reports a completed screenshot, not that the screenshot contains the page you expected. The reviewed sources provide no failure rate or benchmark for Cloudflare-related Thumbalizr captures, so there is no evidence-based success percentage to use for planning.

Thumbalizr announced in April 2026 that it was transitioning its screenshot backend from Browshot infrastructure to ScreenshotCenter in phases, starting with newly created accounts and then moving existing accounts in batches. The announcement said thumbnails, settings, and API usage would continue to work; it did not attribute Cloudflare failures to the transition. If a symptom began around a migration, include your account age and incident timestamps in a support report rather than assuming the migration caused it. Thumbalizr announcements.

Or skip the browser setup

If you need screenshots for pages you are authorized to capture, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.

See the ScreenshotNeo API documentation for the supported parameters and options. Here is a direct request:

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

For a Cloudflare-protected page, a provider cannot guarantee that the site will serve its normal content; inspect the returned image and verdict. ScreenshotNeo’s listed billing behavior means bot checks and failed or blank captures are not billed. You can also use the same endpoint from Python or Node.js:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
    f.write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots. Sign up for free and try ScreenshotNeo.

FAQ

Does an `OK` status mean Cloudflare allowed the capture?

No. It means Thumbalizr reports that the screenshot completed. Inspect the image to see whether it contains the expected page or a challenge.

Will changing the user-agent fix the capture?

There is no Thumbalizr-specific evidence here that changing it is a fix. Cloudflare’s Browser Run documentation says its userAgent parameter does not bypass bot protection; that documentation does not establish Thumbalizr’s behavior.

Can I allowlist Thumbalizr in Cloudflare?

If you administer the domain, use the security events and rules for the actual request to decide what change is appropriate. The reviewed Cloudflare allowlisting instructions are specific to Browser Run, not Thumbalizr.

Did Thumbalizr’s backend transition cause Cloudflare failures?

The April 2026 announcement describes a phased backend transition but does not connect it to Cloudflare failures. Treat it as timing context and include timestamps in a support request.