Thumbalizr Screenshot Stuck Processing: Troubleshooting Steps

If a Thumbalizr screenshot is stuck processing, first inspect the X-Thumbalizr-Status response header. QUEUED means Thumbalizr says it is being processed; it does not by itself mean the request failed. OK means the thumbnail is complete, and FAILED means the capture failed. When a failure reason is available, read X-Thumbalizr-Error. Check request encoding and account settings before concluding there is an outage. Thumbalizr does not publish a universal queue wait or retry interval in the reviewed documentation. Thumbalizr API documentation

1. Read the response status and headers

Capture the response headers along with the image response. Thumbalizr documents these status values:

• QUEUED: the screenshot is being processed.
• OK: the requested thumbnail is done.
• FAILED: the screenshot failed; inspect X-Thumbalizr-Error if present.

X-Thumbalizr-Generated identifies when the thumbnail was generated. A queued response is a processing state, not a promise that it will finish within a particular number of seconds. Save the status, error, and generated headers when diagnosing an issue.

2. Inspect a request with cURL

The legacy API documentation shows requests to https://api.thumbalizr.com/ with an API key, target URL, and options. Replace the placeholders below with your own values. Use --get and --data-urlencode so the target URL and its query string are encoded as query parameter values.

curl --get --include "https://api.thumbalizr.com/" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com/path?campaign=spring&source=app" \
  --data-urlencode "mode=page" \
  --output thumbalizr-response.bin

--include prints response headers for diagnosis; it also includes headers in the saved output. For a cleaner separation, use this version to save headers and body to separate files:

curl --get --dump-header response-headers.txt \
  --output thumbnail.bin \
  "https://api.thumbalizr.com/" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com/path?campaign=spring&source=app" \
  --data-urlencode "mode=page"

Review response-headers.txt for the three status headers. Treat the returned body according to the response and status rather than assuming every response is a completed image. Avoid putting API keys into shared logs or public issue reports.

3. Check URL encoding and request parameters

Thumbalizr specifically cautions that parameters must be encoded correctly, especially url. A target containing &, ?, #, spaces, or non-ASCII characters can be misread if manually concatenated into the API request. Let your HTTP library encode each query parameter.

The API documentation says url is the only required parameter; other values can default to the account profile. Documented settings include thumbnail width, output format, JPEG quality, a timestamp to force refresh on paid tiers, page versus screen capture, delay, browser viewport width and height, and capture country. Check the current API documentation and your account for accepted values and plan access before changing settings.

4. Runnable Python example

Install the dependency with python -m pip install requests. This example sends the target as a structured query parameter, saves response headers, and reports the Thumbalizr status fields.

import requests

endpoint = "https://api.thumbalizr.com/"
params = {
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com/path?campaign=spring&source=app",
    "mode": "page",
}

response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()

for name in (
    "X-Thumbalizr-Status",
    "X-Thumbalizr-Error",
    "X-Thumbalizr-Generated",
):
    print(f"{name}: {response.headers.get(name, '(not present)')}")

status = response.headers.get("X-Thumbalizr-Status", "").upper()
if status == "OK":
    with open("thumbnail.bin", "wb") as image_file:
        image_file.write(response.content)
else:
    print("No completed thumbnail was confirmed; inspect status and error headers.")

A client timeout means your client stopped waiting; it does not establish whether Thumbalizr completed the job later. Preserve the request time and any headers received. Do not immediately create a burst of duplicate requests.

5. Runnable Node.js example

This uses the built-in fetch available in current Node.js releases. URLSearchParams encodes the target URL as one parameter. It logs response headers and saves the body only after an OK status.

import { writeFile } from 'node:fs/promises';

const endpoint = new URL('https://api.thumbalizr.com/');
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com/path?campaign=spring&source=app',
  mode: 'page',
});
endpoint.search = params.toString();

const response = await fetch(endpoint);
console.log('HTTP:', response.status);
for (const name of [
  'x-thumbalizr-status',
  'x-thumbalizr-error',
  'x-thumbalizr-generated',
]) {
  console.log(`${name}:`, response.headers.get(name) ?? '(not present)');
}

if (!response.ok) {
  throw new Error(`Thumbalizr HTTP error: ${response.status}`);
}
const status = (response.headers.get('x-thumbalizr-status') ?? '').toUpperCase();
const body = Buffer.from(await response.arrayBuffer());
if (status === 'OK') {
  await writeFile('thumbnail.bin', body);
} else {
  console.log('No completed thumbnail was confirmed; inspect status and error headers.');
}

6. Check account limits and capture settings

Confirm the account has remaining monthly volume and supports the requested options. Thumbalizr’s feature page lists Free at 100 screenshots per month, Silver at 2,000, Gold at 3,000, and Platinum at 5,000 or more; quotas and features may change, so verify them on the current feature page. The documentation says profile defaults apply to omitted parameters.

• Temporarily reduce the request to the required url and a simple capture mode if optional settings may be invalid.
• Check width, format, JPEG quality, delay, viewport, and country against current docs and the account tier.
• If a cached thumbnail may be involved, review the documented timestamp refresh option and confirm whether your tier supports it.
• Use a target page that is publicly reachable from the internet; login walls or private network addresses may not be capturable.

7. Retry carefully and escalate with evidence

If the response remains QUEUED, check again after a reasonable interval instead of sending rapid duplicate requests. Thumbalizr’s reviewed docs do not set a universal retry period or publish queue depth, so there is no official fixed delay to prescribe. If status becomes FAILED, preserve the exact error header and correct the indicated request issue where possible.

For an unresolved case, contact Thumbalizr support and include:

• Approximate request time and timezone.
• HTTP response code and X-Thumbalizr-Status.
• The exact X-Thumbalizr-Error value, if present.
• Plan tier, relevant settings, and a target URL only if safe to disclose.

Remove API keys, embed tokens, secrets, and sensitive query parameters from logs before sharing them.

8. Migration context

Thumbalizr announced a phased move from its Browshot-powered backend to ScreenshotCenter on April 8, 2026. The announcement said new accounts would move first and existing accounts in batches, while existing API calls and settings were expected to continue working. It does not establish that the migration caused a specific queued request, nor does it confirm the rollout state for an individual account. Use response headers and support evidence to diagnose the particular capture. Thumbalizr’s blog announcement

9. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns an image or PDF; see the ScreenshotNeo 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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").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}`);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month.

10. Performance, reliability, and cost notes

A queued status means processing is underway; the reviewed sources provide no measured completion-time guarantee, current queue depth, or universal retry interval. Keep concurrency controlled while investigating so duplicate requests do not add avoidable work. Check plan quota before repeated captures. Thumbalizr’s migration announcement describes intended speed and reliability benefits from its new backend, but it is not independent performance evidence and does not explain any one request.

11. FAQ

Does QUEUED mean my screenshot failed?

No. Thumbalizr defines it as being processed. Look for a later status or an error.

Where is the failure reason?

Read X-Thumbalizr-Error when the response includes it.

How long should I wait before retrying?

The reviewed documentation does not specify a universal interval. Avoid rapid duplicate requests; if it remains unresolved, contact support with the response evidence.

Did the ScreenshotCenter migration cause my queue to stall?

The migration announcement does not prove that. The rollout was described as phased; check the request’s headers and ask support about the specific capture.