How to Capture Mobile-Width Website Screenshots with Thumbalizr

To capture a website at a mobile-width layout with Thumbalizr, set bwidth to the viewport width in pixels and bheight to the visible browser height. Choose size=screen for the visible viewport or size=page for a full-page capture. The separate width parameter controls the output thumbnail width; changing it does not make the page render at a mobile viewport. Thumbalizr documents that “bwidth and bheight define the viewport of the browser.” (Thumbalizr API documentation)

A narrow browser viewport is a responsive-layout inspection target. The documented settings establish viewport dimensions, not a particular phone model or full device emulation profile.

1. Choose the viewport and capture size

Pick a width that matches the responsive state you want to inspect, then choose a useful viewport height for the visible section. There is no single width that represents every phone. For example, use a narrow width to check whether navigation collapses, text wraps well, and columns stack as expected.

Parameter	What it controls	How to use it
bwidth	Rendered browser viewport width	Set it to the desired inspection width in pixels.
bheight	Rendered browser viewport height	Set enough height to show the section you want to inspect.
size	Capture extent	screen captures the visible viewport; page requests a full-page capture where the plan supports it.
width	Output thumbnail width	Use this for output sizing; it does not change the rendered browser viewport.

The API documentation gives a general dimension range of 1–2000, but plan entitlements affect which custom dimensions are available. Verify the current plan and account before relying on a particular viewport size.

2. Check plan support before capturing

Thumbalizr’s published pages present plan limits differently. Its demo describes Free and Silver as fixed at 1280×1024, while Gold and Platinum offer larger or custom browser dimensions. Its feature page lists custom browser dimensions for higher tiers, with different limits for Gold and Platinum. The Free plan is described as screen-only; higher tiers list full-page capture. Check the live plan details and your account for the exact available dimensions, capture size, quota, watermark, delay, and browser-location options.

Do not assume that a free or Silver account can request an arbitrary mobile viewport just because the API documents bwidth and bheight. If a requested dimension is unavailable for your plan, use an entitled size or change plans.

3. Build and submit the Embed API request

For the Embed API, obtain the API key and secret from your Thumbalizr account. Encode the target URL and parameter values as query parameters. The documentation describes constructing a token from the query and secret; use its current signing instructions rather than inventing or reusing a token format.

1. Choose a target page and the viewport width and height.
2. Choose screen or page, subject to your plan.
3. URL-encode the target URL and other values.
4. Generate the request token according to the current Embed API documentation using your account secret.
5. Send the request and inspect the response headers for its status and any error.

Thumbalizr’s API documentation is the source for the current endpoint, required fields, encoding, and token procedure: Thumbalizr API documentation. Credentials and signing details are account-specific, so this article does not provide a fabricated API URL or token-generation code.

4. Verify the capture result

Inspect the response headers. Thumbalizr documents X-Thumbalizr-Status values QUEUED, OK, and FAILED. The X-Thumbalizr-Error header reports a failure reason. Treat QUEUED as work still in progress, not a completed image; follow the API’s documented retrieval or polling process for your integration.

When the image is available, check the rendered page itself: viewport-width behavior, horizontal overflow, sticky elements, cookie banners, and any content that loads only after scrolling. A screenshot captures the page state produced by the remote browser and its configured viewport.

5. Common problems and fixes

Symptom	Likely cause	Fix
The layout still looks desktop-sized	width was changed instead of the browser viewport, or the plan does not allow the requested bwidth.	Set bwidth and bheight; confirm the plan allows those dimensions.
Request fails or returns an error header	Invalid or missing credentials, malformed token, or incorrectly encoded parameters.	Check account credentials and regenerate the token using the current documentation. Encode the URL and query values correctly; inspect X-Thumbalizr-Error.
Status is QUEUED	The capture has not completed yet.	Use the documented completion or retrieval flow rather than treating the response as the final image.
Full-page capture is unavailable	The selected plan may be screen-only.	Check the live plan feature list and account entitlement; use size=screen if that is what the account supports.
Capture dimensions are rejected or constrained	Custom viewport dimensions are plan-dependent and plan pages summarize the limits differently.	Consult the current plan page and account settings for exact width and height limits.
Screenshot does not match a specific phone	Viewport dimensions alone do not establish model-specific device emulation.	Use the capture as a responsive-width check, and verify device-specific behavior with an appropriate device testing setup.

6. Performance, reliability, and cost considerations

• Keep the viewport purposeful. Capture only the visible screen when that answers the question; full-page captures cover more content and may take longer to render.
• Use dimensions your plan supports. Custom browser width and height availability depends on tier. Published plan details include quotas and options such as delay and browser location; confirm current terms before budgeting.
• Account for asynchronous status. A queued job is not complete. Build request handling around the documented status and error headers.
• Budget against quota and watermark requirements. Thumbalizr’s pages list different monthly quotas by tier and describe a watermark on Free. Published prices can change, so check the current plan page before purchase.
• Do not treat a viewport screenshot as device certification. A width-based capture helps inspect responsive breakpoints, but it does not prove behavior across physical phones, operating systems, or browsers.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Its GET API returns an image or PDF from one request. It can capture a page at a chosen viewport, with options for full-page screenshots, device presets, and other capture controls. 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, with no card.

FAQ

Does setting a narrow width emulate a named phone?

No. The documented parameters define browser viewport dimensions; they do not specify a model-specific device profile.

Should I use size=screen or size=page?

Use screen for the visible browser viewport and page when you need a full-page image and your plan supports it.

Why did changing width leave the layout unchanged?

That parameter sizes the output thumbnail. Set bwidth to change the rendered browser viewport.

What does a failed status tell me?

Check X-Thumbalizr-Error for the documented failure reason, then verify the request, credentials, signing, and plan-supported settings.