How to Capture a Webpage Screenshot with URLbox at Mobile Viewport Width

To capture a webpage with URLbox at mobile viewport width, set the render options width and height explicitly. For example, width=390 and height=844 create a 390-by-844-pixel browser viewport; those are example dimensions, not dimensions that apply to every phone. URLbox’s documented defaults are 1280 by 1024, so omitting the dimensions leaves the browser at desktop-sized defaults. [URLbox Quick Start; Render Options]

Use a mobile-sized viewport with URLbox

Choose the target URL and image format, then pass the viewport dimensions. URLbox’s quick-start example uses PNG and a 390-by-844 viewport. Replace the example page with the URL you want to capture.

https://api.urlbox.com/v1/{api-key}/png?url=github.com&width=390&height=844

This is the documented render-link shape, shown here to explain the options. For an actual project, use its credentials and the URLbox authentication method appropriate to the request. Do not put a secret key in public client-side code.

What width and height control

width is the browser viewport width in pixels. Set it to the narrow layout width you want the page to respond to.
height is the browser viewport height in pixels. Set it too when you need a predictable viewport for repeatable captures.
thumb_width resizes the resulting image; it does not make the browser lay out the page at a mobile width.
retina=true requests output equivalent to device pixel ratio 2.0 (@2x). URLbox notes that output dimensions double and processing may take longer. Retina changes pixel density, not the viewport layout.

A mobile user agent is a separate setting from viewport dimensions. URLbox documents a mobile user-agent option that uses a modern iPhone/Safari user-agent string. Add it if the page responds to browser identity; setting it does not replace a narrow viewport.

Choose viewport, user agent, and pixel density

Setting	What it affects	When to use it
`width` and `height`	Browser viewport dimensions and responsive layout	Always set these for a predictable mobile-sized capture
`mobile`	Browser user-agent identity	When the page varies content or behavior based on user agent
`retina=true`	Output pixel density (2.0 / @2x)	When a sharper, larger pixel output is useful and extra processing time is acceptable
`thumb_width`	Resizes the generated image	For a smaller output image, not to change responsive layout

Compare captures by recording viewport width and height, whether the mobile user agent was enabled, and whether retina output was enabled. These settings change different things, so changing several at once can make a visual difference harder to diagnose.

Use URLbox authentication safely

For production render links, URLbox’s quick start recommends secure render links. It describes a token generated as HMAC-SHA256 of the query options, signed with the secret key. Generate that token on a trusted server; never expose the secret key in browser code. The API reference also documents bearer-secret authentication for API requests. Use the method documented for the endpoint and integration you choose. [Quick Start; API Reference]

If you use the synchronous API, POST to /v1/render/sync with the URL (or HTML), format, and desired dimensions. The response includes a renderUrl and size once generated. The temporary render URL expires after 30 days, so retrieve or store the resulting image according to your application’s needs. [URLbox API Reference]

Troubleshooting mobile captures

Symptom	Likely cause	What to change
The screenshot still looks like desktop	The viewport dimensions were omitted or a different option was changed	Set `width` to the intended narrow pixel width and set `height` explicitly. URLbox’s defaults are 1280 by 1024.
The page layout is mobile, but the content differs from a phone browser	The site may vary by user agent as well as viewport size	Try URLbox’s `mobile` user-agent option in addition to the dimensions.
The page layout did not change after enabling mobile user agent	A user-agent string does not set the viewport width	Set `width` and `height` independently.
The image file is wider or larger than expected	`retina=true` doubles output dimensions, or image resizing was confused with viewport sizing	Disable retina if you do not want @2x output. Use viewport dimensions for layout and `thumb_width` only for output resizing.
A signed render link is rejected	The signature may not match the query options, or the wrong authentication scheme may be used	Generate the secure-link token from the exact query options using HMAC-SHA256 and the secret key, or use the documented bearer-secret method for the API request.
A saved render URL no longer works	The temporary URL has passed its documented 30-day lifetime	Generate a fresh render and persist the image where your workflow requires longer retention.

Performance, reliability, and cost considerations

Start with the smallest output settings that meet the use case. Retina output doubles image dimensions and may take longer to process, so enable it only when the extra pixel density matters. A fixed viewport height also makes runs easier to compare, while the page’s own content can still vary over time.

The supplied URLbox documentation establishes parameter behavior and the temporary render URL lifetime, but it does not establish universal capture timing, identical rendering across all sites, or a price for a particular plan. Check the current URLbox account and API documentation for applicable limits and charges. For production, handle request failures, keep credentials server-side, and account for the 30-day expiry of temporary render URLs.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return a screenshot as PNG, JPEG, or WebP, or a PDF. Its options include viewport presets and custom viewport sizing, but the URLbox parameters described above are specific to URLbox. See the ScreenshotNeo API documentation for its 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

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}`);

Cookie banners are accepted like a visitor, and 60+ known consent platforms, newsletter popups, and chat widgets are removed before the screenshot; each step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers identify the page verdict and whether it was billed.
An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

FAQ

Does a 390-pixel viewport mean every phone is 390 pixels wide?

No. It is the example width in URLbox’s quick start. Choose dimensions that match the layout or test case you need.

Should I use a mobile user agent or a mobile viewport?

They affect different inputs: viewport dimensions control available layout space, while the user agent identifies the browser. Use either or both based on what the target page responds to.

Does retina mode make the webpage use a narrower layout?

No. It increases output pixel density. Set width and height to control viewport layout.

How long does a synchronous render URL last?

The URLbox API reference says the temporary renderUrl expires after 30 days.